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It’s a jungle out there when it comes to operating system upgrades and the ever increasing minimum system requirements 
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in the oLd days, if you were designing web pagei, you had two choices: a} make the type Look good using a bitmap ^ and Lose 
the ability to have your text indexed, searched, copied, or speU-checked, or b) use a generic web font. 

That's history. With Photofont technology, your website can boast impressive typography, yet keep all the advantages of 
standard HTML text Test it yourseLf at http://www,photofontxom 


Photofont® WebReady^” Lets you format web headlines and other 
short web texts with any fonts available on your computer without 
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And search engines such as Google will Like your pages, too! 


But Photofont® technology allows you to use more than just the 
normal fonts. You can also use photofonts with full color or 
grayscale, gradients, transparency and cool effects. 

With BitFonter™, you can make photofonts out of any digital image. 
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FONT EDITOR HEADQUARTERS 


Our Photofont® plugins for Adobe Photoshop®, Adobe inDesign® 
and QuarkXPress* allow you to use photofonts in any print 
publication as well as on web pages/ 


Fontlab Ltd. is the world leader in font editors and converters- 
TypeTooL^”* TransType^”, Fontographer^'^, FontLab Studio^”, AsiaFon 
Studio'^'^, BitFonter^*^* ScanFont™ and more. 


VISIT US AT WWWJONTLABXOM AND WWW.PHOTOFONT.COM 


Copyright © 3007 by Fontlab, Ltd, Inc* BitFonter™, FontLab®, Photofoitl^, TypeTboF**, Fontogjapher™, FontLab Studio™, AsiaPoni Studio™, TransType’ 
Fonilah Ltd. Inc. Inl>eslgn<g^ and PhotoaJiop© axe registered trademarls^ of Adobe Systems, Inc. QtiaikX Press is a trademark of Quark Inc. 
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From the Editor 
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|c\sL pnic:lit:e,s7 Ir's a phrase dial's been on my mind lately. A lot. Possibly because IVe had 
interaaions with what 1 can only consider '‘worst praaices." However, 1 really dislike the phrase 
altogether - there’s no such diing, really. At Ica^si, nt>t in die way it’s typically pa^sented. *lhe 
best practices applicable to any given simation change with the situation, as no two are jicrfect matt lies, 
'rhere are ways to try to make processes more effitieni and predictable. Ihose are the ttxils yt>u need in 
your toollxix, Keach for them often, and understand liow they work. That way, you can turn any situation 
into one using “liest practices.” 

Speaking of which, we liavc some articles this month that foil right into this category. Philip Rinehart 
leads us through an introduction to afp54H;s InstaDMG, a more formalized way of creating lull OS installs 
tlirough packages. Deployment of systems in a large environincnt is a huge challenge, and OS X has all 
of die software built-in dial yoifd need. You just have to decide how to use them. Tlii.s niondrs 
MacEnterprise column tries to make your image-erealion prex’ess a bit more consistent, miKlular and 
auuymatcd. 

Following this, Andy Sylvester presents m with an article on testndrtvefi development using 
AppleScript. On one level, it’s a methodology “ line up your tests in software before you write the ctxle. 
While this article is specific to AppleScript, the meltuxl siLs at a higher level than that and is interesting in 
its own rigliL If you're an AppleScripter* this anicle cun show^ you how^ to build latter, more w'ell-tested 
applications, 

leopard broughi developeis and sys admins a lot of new toys to work and play with, Xcmle 3 alone 
brought great change. One of the beautiful update.s is that more scripting systems have templates buifo 
in that even interact widi CtH'oa. Ruby is one such language, and Rich Warren starts showing us lujw to 
take advantage of that. Check out the great sample apfilic'ation and gel your Ruby grtxwe on! 

Dave Dribin, our resident Cocoa master, brings us further down the road and icraclies you how to 
write a GUI application. If youVe been following along, tliis is the first time diat we're breaking out tire 
GUI while learning Objective C Xcxxle and Ctxxia. Dave shows you the secrets to Interface Builder and 
lKK)king up your ctxle to the GUI. It's the next stop on The Road to Code. 

Also in the “liesi jiratlices” t:ategt)ry: mistakes. We all make them, and we need a way to recover 
Fnd-users have come to ex)X"ct undo stippon in ilieir favorite applications as a w^ay tt> return to a state 
pre mistake. Rut not every applicaiion supports undo. After reading Marcus Zana’s ’"Grokking OS X’s 
Undo Support," you'll w'onder why. Marcits teaches tiie ins and outs of OS X’s built-in nndt> Manager, 
anti how^ you can make it work in }mtr application. 

This month's Mac In The Shell continues to talk about BHF as a general scripting language, outskle 
of any web use. This lime, w-e specifically sian to deal with database support and data manipulation. 
Mtiving data Ixtween sysicms, or even reporting on a data in a single database are common tasks. If 
youVe Ix^en stymied by doing so in the past, read all about it here. 

Last, [>ut not leasi, the MacTech Spotlight shines on Eberhard Rensch. Founder of Pleasant Software. 
Before GarageBand, and IxTore Podcast Prodticer, Pleasant Softw'are brought us LFbercaster, a [H>dcast 
producing “srudio.” If you're deep into ptxlcrjst, well, you’re probably already using Ubercaster. if you 
want to get into pcxJcasting, Ulxircaster is a great way to gt>. Pleasant St>fiware also makes some other 
cool tools, but, more importantly, we gel some insight frt)m the founder and main develt)per! 

Until next month, keep working t)n yrmr Ixsi praciices. 

Ed Marezak, 

Executive Editor 
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Mac in the Shbu. 

by Edward Marczak 


Data 

Manipulation 


here: http;//code,googlexom/p/phpfr/ (it has been “open 
sourced’' since its introduction, and now lives as a CKK>gle Code 
project)- Weigliing in at close to 40MB, ifs a little larger than 
your average widget, bu\ that's llte price you pay to carry 
around die entire PHF functk>n set witli descriplioas. As a 
Dashboard widget, it lives out of sight until you need it- With 
a search funiiion built-in, 1 tend to reach for this a lot. Higlily 
reconunended- 

The Setup 


with PHP 

PHP provides easy access 
to MySQL on OS X 

_ 


Introduction 

Last iiKJnlh, we covered some of the liasics of scripting 
with Flip This monih, we ll cominue and talk about database 
access and string manipnlation with FUF 'llianks to a pretty 
full install o( FJIP as the default in OS X, we don’t have to 
wony alx)ut fetching, configuring, toinpiling and installing FHl* 
- wr am just get on with writing our script. 

Working Environment 

Ust month, I meiiiioned that there are plenty of OS X- 
based editors that ^understand' I^HF This comes in the form of 
syntax coloring, appropriate code snippets, cckIc completioti 
and auto indentation. Before we continue, there are two more 
things cliat I should memion. 

Oxh, IVoin Panic Software, is one of those editors one 
that I shtmld have inenlioned last month. It's adually quite a 
bit more than a simple text editor: It's a full wel) developmenl 
environment. I really mention it here because it has a way to 
acccs,s FUF dtx'umeniaTion built right in (along with ITI'Ml, 
Javascript and UKJre)* Since FHl^ is such a popular web 
development language, as a w^eb development Icxd, this made 
sen.sc\ Ai Iasi check, though, access to this documentation w^as 
only available while you Itave an Internet conneclion. 

I, on the other hand, am very much of an offline |x.^rson. 
t want/need to aax>mplish things while on a plane, train, or 
wherever 1 may not have a gcxxl signal from some sovtrc'e, lor 
whatever reason. Due to that, Fve come to ady on the FHF 
Function Reference widget for Dashlxjard. Dow^nJoadable from 


1 do a lot of data manipulation and migratitm work, and 
scripiing languages are an essential part of the process. Ferl, 
Rul]y and Python arc all gotxl contenders for that position, but 
this particular column is alxjui PHF! Our sample project tfiLs 
month will extraa data from a MySQL database and give us a 
CSV file, ready for importing into another sy.stem. “But Ed,” you 
say **you can do ihi4t with MySQL alone!’' While this is true, we 
aren’t allowed to manipulate the data U)o drastically in liiat 
pnxess. 

Let'.s imagine tlial the data in our source system is stored 
with a single column for full name, but our target system w^anLs 
separate first name and last name. Or that we need to go 
gather more data (like a ?.ip+i based on address) per record. 
There Lire hundreds <jf reastjns you may need to filter the data 
as it goes from the databLisc to a CSV hie. 

Connecting to the Database 

One variable type thai 1 left out of our discussion last 
mc>nth is rvsourca We lcx>ked Lit string, integer and other built- 
in types, but 'Resource' really warrancs ics own disc'ussion. 

A VLiriLible of type “resource’' holds a reference to some 
exlcmal resource. Tliis may lx- a file on disk, a curl session to 
fetcli a URL. a datalrase conneclion tx more. Again, it’s just a 
reference, and you 11 need tf> ttse functions that know how to 
access iluxse resources via I lie resoiirc'c VLiriahle that you pass 
to them. 

First thing that our script needs to dt> is open a connection 
to the MySQL server. This happtms with the mysql connect 
nimmantl: 

^connection ** 

0iyiiql_coiuiect(“ server-example, com" . "user’', "password") : 

The mysql_connect command pLisses back a re.sQurce if 
,succe,ssfuL and FALSE if there’s an error, lx!i“s get into gcxxj 
habits right aw^ay: check the value of $connection for 
FALSE. Tliankfully, we have access to tile error that the server 
fi;!s,ses back to us in the form of two functions: 
mysql_errno{) and mysql_error{). Tliese functions 
return the error code from the previous MySQL operation. We 
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should follow OLir cooneot, or any datalxiso opcraLion with 
something similar to this: 

if (1 $connection) I 

print ''Connection to database failed 
" .iDysqI_e!:riici(). ” ■ “ .iijy3qI_e3:rot () - " Vn”: 

diet): 

1 

Simply, if $ connection is not TRUE (zero, or, FALSE), we 
print out a message containing the MySQL emjr information, 
and then we halt operation of the script and exit with die (). 

Also, Icjoking at our initial connect string, what’s wrong, or 
at least, what should send shivers up your spine? Yes, a 
password in a script. Unfortunately, that’s just life in the big 
city, and yoifll need to take precautions that allow only the 
riglit jieople to have access to the script. While you can put tliis 
information in externa] files and [>ul] it in, or make your script 
get it from mmewbere, the person that can read your file can 
also (typically) read how and wliere to get the password. Here 
be dragons, so, be conscious of this and plan for protection. 

Once connected, we need to specify which database we're 
going to lie working with. That’s done with the 
mysql_select_db{) function: 

Sselect “ select dbt'V.iJstnmers'') : 

checking here 


All subsec|uenr MySQT. functions operate on the selected 
database. If youTe working witli more than one server, you can 
optionally pass in the connection resource that you obtained 
from mysql_connect ( ): 

$connl=]iiy!jql_ccirinect ("serverl" , "bob", "s3kret"J : 
Sconn2=mysql_connect C“server2" . '’jane" , "hidden") t 
SselecLl“inysql_selecL_db [ " sales" , $connl) : 
$select2=mysql_select_db ("aggregates”. $conn2); 

...with the proper error checking, of course! 

Once those preliminaries are complete, we can now^ query 
our database. While you can stuff a query into fewer Lines, 
weTe going to split it up in a more conventional manner. The 
mysql query{) function takes a string as an argument. 
Assigning the query to a variable makes for easier reading, 
easier variable substitution, and allows one to build dynamic 
(|ueries. Let’s start with a simple example; 

$qitery="select Uid , fnajne, Iname from users”' 
Sreault=Ti!ysql_query ($query); 

$query Ls a simple string, and $result is of type 
resource. As with our earlier queries, if the execution fails, 
mysql_query () will reiurn a RiK)lean FALSE, and our errors 
can be retrieved with mysql errno( ) and mysql error ( f. 

$ result is simply a resource, and points to the result set. 
We now have tc3 ustMt to fetch the actual data, database row' by 
datafjase row. If you purposefully limited your ([uery to a single 
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row, you could now go fiicli il with one line. However, more 
often tliiin not, you’re expecting multiple rows - sometintes 
thousands. A perfect job for tlie while lcK)p i\m we tntnxluced 
last month: 

while ($rov=iiiysq^l_felcti_assoc ($restjl t)) t 

print “Scanning ^,$rowpuid’j ■ "< **$rowl*fnaiDeH 
",$row{*lna»e“],"\n"; 
i 

'rhat’s a lot packed into a small space, m), let's break it 
dowm. The data feLching hapi)cns witli this line: 

$i:ow“ti)ysql_fetch_aefloc ($remilt) 

You could manually call that over and over and get a new row 
from the database eacli c^tll. Of aHirse, tor large result sets, a 
loop IS the only fcasihle method. The 

iny5ql_fetch_as50c() function returns an associaHtfe 
army. Unlike a “plain" array, you can access values with a key 
that is a string. In our case, eiich column from the database 
lx.^<x)mes an entry in the array. We asked Ibr the fields, “iiid", 
’Tiianie" and “Iname", whicfi makes $ row I’Jecome: 
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..filled with the vjilues from ihe t iiiTeni row retrieved from tile 
diitiilxiKe. 

Witliin the body of the kwip, there’s a single line: a print 
statement. Ifs fairly ugly, tliougli, isnl it? It fmpfX'ns to lx 
pretty standard fare in PHE The concatenation operator 
‘glue's’ two strings tt>gether, nt>w' it .should lx pretty easy to 
break dowm, as we're printing some .static text (the bits in 
quote-s) and some dynamic text, filled in by ilie values in the 
$row array. Sample output would ltM>k like this: 

Scanning 1052; Hike Bollinger 
Scanning 1033; Laura Wilkinson 
Scanning 1053: ioanne Hoss 

Now that we have at:cc.ss to our data, let's get it into a 
fonnal usable by almost all other apps: CSV. 

Data Manipulation 

If you simply wanted a CSV RIe of a MySQf- database l ahle, 
there are many simple ways to do so. However, when moving 
diila frrmi one system to another, w'e often need to massage the 
original data into a new format. We get that opportunity^ in our 
while loop, w^here we're accessing each row of the table and 
ixfore W'riting ii out. PHP ha.s many slritig mafiipulatton 
fnticliom to help us do anything our hearts (and brains) desire. 

The first thing we may want to do is to simply re-assign a 
cleaned-up version of a string IxTore writing it out. Consider 

dlLS: 



switch ($rciw['i 3 tate' 1 ) 1 
case “NY"; 
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case “nev york" : 
case "noo yrk”: 

$state="Kew York"; 
break; 
case “GA“: 
case “calif 
case “cal"; 

$state-"CaliforHi a"; 
break; 
default; 

$st3te-"Ufvkno%/ii": 

I 

Kather than writing six separate if slatcnients, I chose to use a 
single switch stalemenL This is aj cleaner code and b) a nice 
Introduction to the switch statement, which I did not cover 
last month. Generallyj the switch siaiernent will test a single 
expression for llte resulis you choose to test for. In the 
preceding example, were examining the variable 
*'5row[ 'state' ]". Eiich case stateineni within the switch 
block aas as an “ir .sintement, and all ccxle through the 
following break, statement is executed. The code in the 
default blcx'k matches when no other ease statements 
match. While the switch statement may ctmtain virtually any 
expression, the match in each case statement can only be a 
simple ty[K‘: string, integer or floating-j^iini. You onnol 
evaluate arrays or objecls here. For these more complex cases, 
you still must rely on an if statement. 

Tlie simple line doing all of the work here is this: 
$state="../'. We’re [Usr assigning a literal to oitr varialile. 


We're even free to re-assign $row[ 'state' ] tf it suits our 
needs and style. 

One of the coolest ways to tear up a suing Is tlie 
explode () function. As always, an example is l^st: 

Sanimal=''l3ear ait dog elephant"; 
lthe_antmals:=expl(xM“ **,(animal); 

After this runs, $ihe_aniiiials will fx? an array containing: 

$the_a ni mal s(0]-"!x'a r" 

(ihc_anima]s{l]="cat'' 

$ l 1 le^animal s| Zl^^'d og” 

(the_ammals[3l=''elephant" 

explodd) am split based on any delimkr^ not just a space, 
I lowevet this is extremely iisehil for spliiting u]> a full name. If 
you krmw that all entries in the datilrase are in firstname-space- 
lasmame formal, ilien this will do what you want: 

list ($fn0ine, “ exp lode (“ ^ * Sfuliname); 

However, the reason youTe probably involved is due ti> a 
more complex nature of the data. If mosl names are in two- 
name format, but some may contain a middle initLil, too, then 
we have a few options. One would be to toss the middle initial, 
or include it in the first name. In rli;it scenario we need to test 
how many elements were returned: 
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lam S* Fat ire**: 

$Tianies-expio(ie(“ ’*tSfuliname3: 
if {count > ?.) I 

Sfnaiie=$naroes tOJ *" **. $uanies f 11: 

Slriaiie-$naisesf2l: 

I else ( 

$fna»e“$najnepfOl: 

$lnaiie=§Tiaaies UJ» 

I 

print “The naraca are:\n“; 
print “Firstname: $fnaine\n“: 
print “ La at name: $lnameVir: 

'[Tie count () funclioii i.s inlroduced here and simply returns 
the number of elements in an array. 

Naturally, our target datahase may have a field for middle 
initial, in wliich case, we tan retain it and assign it 
appropriately. 

lets now imagine that we want to ca*ate a default user id 
for t)ur ttcw users. We am bstse this id on the user's real name. 
PI IP includes some nice string slicing functions. If we want to 
base the user ID on the aser’s first initial plus last name, that's 
simple: 

$uid‘^$fnamc[0] .Slnatae: 

PUP can access siring elements hy character when you sujjply 
the zero-based offset in square brackets, So, in this example, 
weVe just grabbing the first character of $fiiame. 

If you had a more complex uid<reation scheme, it'd he 
easy to handle, loo. If ytni needed a ui<I that contained the first 
three letters from the family tiame, and the first two from tlie 


first name, PUP includes a nice sulKslring fundion, Generically, 
it ltK>ks like this: 

substr ($si:i:ing* $start l.$length 1 ) 

This will reutrn a string that starts at 'Jstan‘ in (string, and 
aias Lmtil the end of the string supplied, or optionally, for 
(length. Back to our first-three, fiDit-iwo lud s<'heme: 

Suid“substr{$lname*0*3) .fiyfeKtrt§rnarai?,0*2): 

Nice, right? Of course, if you were really implementing thLs, 
youd need to look for duplicates and alst> check for bsi names 
that may be shorter than 3 characters in total (like “LD. 

All Together Now 

rd like to put all of this logeiher to create a code snippet 
tliat takes data from a datal>asc% gives spiicie to manipulate the 
data, and output a CSV file. Simte new elemenLs will also l)c 
intjxxjuced here. 

Li^Unfi 1: dbZcsv.php 
Oi <?php 
02 

03 iiysql_connect(“12/.0.0.1“« "dbuser“, “dhpass") or 
0^ dle(“Could not connect: “ . iny!iql_ei:ror0J: 

05 iiyiJql_selGct_db(“raydb’*) r 
06 

07 $q=‘^select * from user_profilefi order by fid**; 

OS $r“mysql query($q); 

09 while t$row=Tiiysql_fetch_assoc{$r}) t 

10 $pf[$row[*f1d*]]-$fi>wI'ii tie'll 

11 I 

12 



MacSpeech' 

Dictate 

2008 is the year everything changes 
for speech recognition on the Mac. 


Discover the new generation of amazing speech solutions for your Mac 

http://www.MacSpeech.com 








MAC0SX10.5 

LEOPARD 



Mac OS X 10,S Leopard: 
Visual QukkStart Guide 
ISBN: 0321496000 
Marta Langer 

Available now I 



Mac OS X T0,5 Leopard: 
Peachpit Learning Series 
ISBN: 0321502639 
Robin Williams 

Available now! 



Automator for Mac OS X 10.5 
Leopard: Visual QuickStart Guide 
ISBN: 0321539354 
Ben Waldte 
Available now! 



Mac OS X Support 
Essentials sscoihi Edwon 

a diwida ki BMiipwlinii ilaii; 091 tOJl 


■JSL 


Apple Training Series: 

Mac OS X Support Essentials, 
Second Edition 
ISBN: 0321489810 
Available nowl 



Mac OS X Server 
Essentials Second Edition 

A to Uiiiua wtd toiuiwiitta os 



Apple Training Series: 

Mac OS X Server Essentials, 
Second Edition 
ISBN: 0321496604 
Available now! 


M 



Are you 
ready for 
Leopard? 

Learn the ins and outs of all the 
new features in Mac OS X 10.5 
Leopard.including Time Machine, 

Spaces, QuickLook, Automator, and 
more. Whether you're an experienced 
Macintosh user ready to hone your 
trouble-shooting skills, or you're a 
beginner who needs help getting started, 
pick up a Peachpit book today to get the 
most out of the powerful features 
in Leopard. 


BUY NOW AND SAVE 



Purchase or preorder your copy today 
and save 35% off the list price, plus free 
domestic shipping. Simply go to 
www.peachpit.com/ieopartl and enter 
coupon code PP-LEOPARD when you 
reach the checkout page. 














































13 // Create tbe header 
H $curcsv=”\"uid\"I": 

15 foreach ($pf as $key=>$val) I 

16 $cui:csv-Scurcsv. ; 

17 ) 

18 5c\jrcsv=substr (Scurcsv,0.strlen($CTjrcsv) ■ 1); 

1^ pr int "ScLircavXti": 

20 

21 $q="select * froia users where status™!": 

22 $r-]iiyBqI_query{$q); 

23 while ($rtjw"TnysqI_fetch_ausuc($r)) [ 

24 // Build CSV for current user 

25 Scurcsv="\"".$row[‘uid'] 

26 foreach C$pf as $i=>Sval) I 

27 $q2=''select value From u$er_pfqflies where ftd=$i and 
uid“".$row['uid'I: 

28 $ r 2==inys ql_q ue r y E $q2); 

29 $row2=rayaql_fetch_aEsoc(Sr2): 

30 $curcsv=$curcsv . , $rowZ [' value' ] . i 

31 } 

32 $curcsv=aubstc($curcsv* 0HsLrlenE$catcsv) 1); 

33 print '*$curcsv\n'': 

34 ] 

35 

36 ?> 

Newly inrrocliicecl here is (he foreach Itxip. foreach 
^ives the programmer an easy way to iterate over arrays. 
Generiolly, foreach looks like this: 

foreach (Sarray as $value) 

The loop interates once for each element of the aitay, and 
$valLie is ufxhiteci accordingly. A variation to this (seen on line 
26 in listing 1) also includes the CLirrent key - very useful for 
assexiative arrays where the key is text or other representation 
of the index, lliat variant is simply: 

foreach ($array as $key^>Svalue) 

Breaking down listing I, lines 1-5 should look familiar: the 
opening PHP tag, and Qien try to corinect to tlie dataliase. Line 
7 defines the first query lo the first table, and line 8 executes 
that query against the selected database. The while kxjp 
starling at line 9 is pretty standard fare, bill what's going on in 
the loop ixxly? 

On line 10, we’re creating an as^sexiative array ($pf) using 
a variable as the key (“index''). In this case, weVe using the 
result of the database fetch $row[' fid' ]. Pretty slick. 

Lines 14 through 17 take case of one small hui significant 
pad of writing out a CSV file: making the first line a header that 
descrilx^s the remaining columns. In our case, we can do that 
with the contents of the array we just created. Another 
foreach loop neatly solves that. In the htxly of this kx>p, 
we're creating a variable that will hold the cunent line of the 
CSV file. Each field is wrapped in quotes, and then followed 
by a comma. 

Line 18 removes the trailing comma from $curcsv, and 
line 19 prints out Scuresv. Now^ for the bulk of work. 

Lines 21 through 33 handle the main load of this program. 
Line 21 and 22 set up a new t|uery and execute it. Line 23 
brings back our now familiar while loo[3, fetching one database 


row at a time. lane 25 starts $curC5v anew eaich iteration, 
wrapping the proper value ($row['uid'] in this case) in 
quotes followed by a comma. 

Line 26 gets interesting: we use a new foreach kx^p to 
obtain more inforaiation about this particular iiid for each of the 
values in $pf - by ninning a new query, We c^ueiy and fetch 
agjtin, and line 30 adds each field retneved to $curcsv 
(wrap^x^d and comma'd). 

Finally, line 32 takes care of the trailing comma on 
$curcsv (because we blindly add it after each value), and line 
33 prints llie row. 

Running tliis, or similar program, will simply dump all 
output to standard out “ we're only using a print statement. 
You thiiughl we were creating a CSV Jile^ Well, we are! 
Everything in Unix is a f ile. Rememlxr our shell redirectors? We 
can nm this program as is and have the chance to visually inspect 
the output, and, when we’re ready, sinij:>ly redirect to a file: 

php db2csv.php > users,csv 

Tins is also a nice euphemism fex, Tm going to cover file 
manipiilarion next month!" 

Conclusion 

I'll continue to say: don’t discount PHP as a general 
scripting language. It's fairly rii]>id develt^pmenl, has broad 
capaliilities, and will typically be found across phitfoniis 
(including ven?ic?ns for Windows - but you'll need to install it 
yourself). As mentioned, HI cover sotne more aspects of 
scripring with PHP next nitmilu including file manipulation. 

Media of the month: Inside the iMachine: An illustrated 
Introduction to Microproce.ssor.s and Computer Arehiteeture, by 
Jon Stokes. IPs a very readable introcluciion to microprocessor 
arciiectui'c, and it's even current enough that it covers up 
through Intel's Core 2 Duo chips. 

Until next rime, enjoy your new sci ipting prowess! 
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Test-Driven Development 
Using AppleScript 

Using testing frameworks to create more 
robust AppleScript applications 


by Andy Sylvester 


Introduction 

AppleScript can Ik liscd to auloTnate many tasks on the 
Mac. However, compared to other scripting languages sik h as 
Perl, Python, and Rnhy, it am seem somewhat simple and not 
as applicable for writing larger appliaitions. ITiese other 
languages also have testing fmmeworks that can l>e used for 
building and testing applications, and have giK>d support for 
objeci-orienied prt)gramming. A testing framework for 
AppleScript allied ASUnit lias lx.‘en developed, which provides 
a way to test AppleScript functions. Altlmugfi AppleScript does 
not natively support OOP in the common way of Perl, I^thon, 
and Ruby, you c'an structure scripts lo provide much of tlte 
same functionality, '['his article will imroduce the amcepts of 
lesi'driven development and demonstrate the use of the ASlJnii 
testing framc^'crrk. 

Describing test-driven 
development 

One ol the signifiaint changes in software development 
techniques in the past ten years has tK*cn a tcchnitjue cal led 
‘Tesi-driven developments When using this develo]>nienl 
technique, the software developer writes a small amount of 
source crxie tt) test a function or feature in the application 
lx.*ing developed. However, the strftware develofXT writes tlie 
test axle Ixfore writing the actual application code. A summary 
of the technique is as lollows: 

Write some test code 

Run llie test and see that it fails 

Write die source ctxle that implements the feature 

for the test 

Rim the lest again and see that it passes 

Retactor or clean up source <-ode 


By writing lest c(xlc txfore writing application code, the 
software developer creates a suite of lesLs llial am lie used at 
any time to check the funciionality of the application. In 
addition, if cliangcs are made to the application, the test suite 
can be uin to see if the existing functions have been affected 
by the changes, 'lb su]ipon test-driven development, many 
testing fraiiK.‘wc)rks have been developed to assist software 
developers in creaiing, running, anti managing tests. Kent 
Beck's work on testing frameworks for Smalltalk 
(hRp://www,xprogramming.cqnri/lestfrarTi.litm) led lo the 
development of die Junii testing framework for the Java 
language (hltp://www.juniJ.or 9 ). Since the appearance of jimit, 
Icsiing frameworks have lieen ileveloped for all prognumiiing 
and scripting languages, and even for web-based application 
development (see hRp://www.xprogromming.conn/ 
software.htm for a list of available framc^works). The second pan 
of this article wall introdiu e a testing framework for AppleScript 
called ASUniL Before learning about diis framework and how 
to use h, let ns first look at some examples to see how writing 
tests can lielfj with application deveUipment. 

Exploring test-driven 
development 

One way to add tests to an upjdication is to use dialog 
boxes to give information on if a test passes or fails. A simple 
test to clieck a niaih ofieniiion txmld be written as follows: 

display dialog “Test fl*’ 
if I + I Is equal to 2 then 

display dialog "Test I passes!" 
else 

display dialog "Test 1 falls!" 
end if 

For this example, a set of dialog lx>xes would he 
presented, first announcing the title of tlie test, tlien the test 
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result. However, this could gel awkward ([uickiy, Iraving to click 
on buttons to allow the progiatii to nm. Also, it is difficult to 
perform test-driven development, since the test code is 
intertwined with tlie application logic. Anotlier approach is to 
create functions that contain application logic and then run the 
functions with rest data, fhls would make it easier to rest 
individual features without affecting other functions. Following 
the test-driven development philosophy, we wiD write a test 
funaion for application logic that checks for a specific input 
string. The following code demonstrates ihis teciinitjiie: 

script myHameGame 

Checkf crHyNaiie [ “Andy") 
end script 

run myNaneGanie 


When diis script is run in the Scri[:)t Editor, a dialog Ixjx 
appears with the error message "ttscript myMameGamen 
doesn't understand the CheckForMyName 
message". Ttiis is U} be expected, since ihe function 
CheckForMyName does not exist, far, we are following the 
checklist of steps given above. Next, we add application logic 
for the CheckForMyName funclitin: 

fin CheckForHyName (L ) 

if testGuess is equal to “Andy“ then 
reiurn “Your gues/s is correct 1" 

else 

return ""Nopel Try again!” 
end if 

end CheckJi'orMyMEUne 

script myNaineGame 

CheckFo rMyName{"Andy") 
end script 

run myNameGame 

The scri[)t myNameGame calls the function 
CheckForMyName with i\n inf)ut string. Tlie results from the 
rest appear in the Results area of the Script Editor window. 
Wlicn this script is run, ihc expected result appears (Your 
guess is correct 1). We have completed all but the last 
step of the our test-driven process (refactor and clean up). 
Since this logic is preiiy simple, we will move on to adding 
some new features. Once again, we start with adding a test. Tlie 
new feature to he added is tliat the function should check for 
the .string “Andy” or ”Biir. We can msidify the myNameCfame 
test to use “Bill’’ as the test string instead of “Andy”. Wlien we 
mn the script, we get the failure result (Nope! Try again!). We 
can now add logic to check for Ixith strings. Otir funtiion now 
looks like Lhis: 

on CheckForMyName(testGuess) 

if (te^tGuess le equal to "Andy“) or ’ 

(testGuess is equal to "Andy") then 
return “Your guess is correct!” 

else 

return "Nope! Try again!" 
end If 

end CheckForMyName 
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script ayNanteGame 

Che ckFotKy Name ('‘Bill "*) 
end gcrlpt 

run TnyNamnGatw? 

When tliis script is mn, the successful result appears again 
(Your guess is correct!). Now we can keep adding 
feature after feature using this tcst'-driven dcvclopnienl 
technique and make sure that the application logic is working 
corretlly. 

As im^re functions are developed, though, this simple tenSt 
structure could be a !>urden tu maintain, If each function to lx; 
tested had to be in its own file, this could result in many 
interinediale files for development. Also, the alxjve structure is 
set up to only run one test at u lime on a fimction. If running 
multiple tests wea* desired, the test script would have to l>e 
edited each lime. Now that we have demoastratecl tlie basic's of 
test-dnven development, let us Itxik at a testing framework that 
can address the maintenance aspects of developing and 
running multiple te.sts on mulfiple hmctioas, 

using asunit 

ASUnil is t'oniained in a single AppleScript file. To install 
tile program, download die latest verskm from die ASUnil 
website (httpr/Znirs^freeshedorg/osunit/), unzip the file, and 
copy the file ASUnil.sept to die Scripts folder in your Library 
folder or ilie Lllirary/Scripts folder on ilie stanup disk for your 


Mac. ‘ITie renxiining flies are the README file for the 
application and a web page containing the ASUnit 
dtx’Umentation (this page can aLsi> be found on the ASUnit 
w'ebsite). 

When cTcating an ASUnil test script, you must include a 
path to the IcKrtRion for ASUnit^sept. Here is an example: 

property pareiu : load script file"* 

(("Sylvester HOtLibraryrScripts;") h "ASUolt,scpt") 

Note that the path to the ftle needs to use the POSfX form 
with colons. 

Next, we need to create a test fbcUire, or a framework, that 
will contain the tests that we wish to write. In ASLInit, rhi.s test 
fixture is an AppleScript which will comain oilier scripis within 
the main script. We can use the follow'ing structure: 

script |«iccessing listj 

ptoperty parent : registerFixture(neS 

property esipty ; nissing value 
property not limply : missing value 

At the lieginning of this script, the registerFixture 
script object is t:alled. Tills ,stTipi objeti is included in 
ASUnitsept. The accessing list scrifn creates a profx-riy using 
the parent reference (which was included in the script file as 
the first line) to be able to access the registerFixture 
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script object. Using tlie me keyword tells registerFixture 
that the accessing list script object is the fixmre. 

The Iasi two lines define [)rofx;rik:s for ol)jeas lhai will be 
used in the test scTipts tliat follow. For this example, two lists 
will be used (one that has no elements, and one that has at least 
one element). 

When running ASUnit test scripts, diere is a setup script 
object which can be overridden with a local version to perform 
setup of objects for och test. Tliis script will Ixr called for each 
test script within the test fixture. For our example, w'C will 
create the two lists as follows: 

□n sijttlpO 

set empty to I] 
set noLEmpLy to ("roo". l) 
end 


To perform a test, aijcl another script which contains logic 
tt) perform some operation on the lest objects. In this example, 
the objects we are manipulating are the lists empty and 
notEmpty. 

setipt I add item| 

property parent : registerTestCase(me) 
set end of empty to "bat'' 
end 

At the lu^ginning of this .script, the registerTestCase 
script object is called. This script object is also included in 


ASUnit.sept. Tlie add item script creates a pn)perty using the 
parent reference (which was included in the script file as the 
firsi line) to be a[)le lo access the registerTestCase script 
object. Using the me keyword tells registerTestCase tliat 
the add item script object is the test case to be registered. Next> 
the word “l.sar“ is added to the end of the list empty, so that 
there Ls now an elemenl widtin that list 

ASUnit provides a methcxl, should, to check for a positive 
result for a condition. The method takes an AppleScript 
expression as tlie first argument, and an error message as tlie 
second argument. If the result tjf the expression is false, the 
error message will be displayed, otherwise the text “ok"* will be 
displayed for that test. Add the followang line to the add item 
script: 

Rhf>i]1 d (empty contH':ijn.5 “bar*, "no barl!") 

Since the previous line added the word "bar’' to the list, this 
test sJiould pass. 

■|’he final addition to this script w^ill be logic to display the 
test results. ASUnit provides a script object called 
makeTestSuite U> ciilleci a number of test scripts inio a 
single suite to lie rim. For this example, we only have one 
script. However, this function can be used with another ASUnit 
script olijcci called makeTextTestRunner wliicit will run all 
of the tests in a suite and create a window' with die output of 
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the tests. After adding logic to call these ftmctions, our first 
ASUnit test script will lx: as follows in Listing h 

property parent : load script file "• 

((“Sylvester IlD:Llbi:aryrScripte:") & "ASttn!T.ecpt“3 
property suite ; makGTestSuite{**My Tests") 

script I accessing list] 

property parent : registexFixturefiae) 

property empty : itiisfiing value 
property notErapty : ralssing value 

on setup 0 

set empty to 11 
set not Empty to |*foo\ 11 
end setup 

script I add item| 

property parent s registerTestCase(me) 
set end of empty to “bar" 
should(ompLy contains “bar"', "no bar?!*) 
end script 
end script 

run makeTextlestRunner(suite) 

After typing (.he above AfipleScript code in a Script Editor 
window, click the Run button to execute the tests. You should 
see a new window open and display the following text: 

Hy Tests 

accessing list add item ok 

Ran 1 tests in 0 seconds, passed: I skips: 0 errors: 0 
failures: 0 

OK 


'llie one test (add item) passed - h(K>ray! Bui whai if a 
different word than “Ixir” had been added to Uie list empty? If 
we change "bar"* to “bat* in the line adding the text to the fist, 
we get the following tesi results: 

My Taflts 

accessing list ’ add item ... FAIL 
FAILURES 


test: accesRlng list - add item 
message: no bar?i 


Ran J tests in 0 seconds, passed: 0 skips: 0 errors; 0 
failures: 1 

FAILED 

Now you know what a test failure looks like. Once you 
have looked at the test results, you can click on the red Close 
button to close the window, then click on the "Dont Save*’ 
liutton to comfilcle c]o.sing the window. 

Now that a test fixture has been created, you can add more 
tests. AI.SO, within a test, you can have multiple “should’' 


statemenLs to perform more than one check. Listing 2 shows an 
addition to the previous script: 

property parent : load script file 

t(“Sylvester HD:Library:Scripts:") & "ASDnlt.sept") 
property suite : makoTestSuite("My Tests") 

script I accessing list| 

property parent ; registerFlxtiire(jae) 

property empty : missing value 
property uotEmpty : missing value 

on setUpO 

set empty to (! 
sec ootEmpty to f"£oo", If 
end sotUp 

script I add Item I 

property parent : regiaterTestCase(me) 
set end of empty to “bar" 
should(empty contains "bar", "no bar?l“) 
end script 

script I add same item| 

property parent : reglsterTestCaselme) 
set end of notEmpty to "foo" 

should(last item of notEapty is "foo", "first foo 
vanished?!") 

should(first item of notEupty is “foo", "where is 
last foo?!") 

end script 
end script 

run luakeTextTestRunner(suite) 


Running this .script give the Ibllowing resulLs: 

My Tests 

accessing list add item ,., ok 
accessing list ^ add same item ,,, ok 

Ran 2 tests in I seconds, passed: 2 skips: 0 errors: Q 
faJ-lures: 0 

DK 

Since ItoLh of the should .siaiemcnLs were satisfied, die 
single “uk” nic.s.sage was [irinted. If eilher or both conditions 
had failed, their respective error messages would have been 
printed. 

Testing an AppleScript class 

Now that we have a working test script, we can stan 
experimenting with adding some funnions to tesi. In 
AppleScript, we can (trganue functions and data wiiliin a script 
to l>e able to create classes and objects like other languages. As 
an example, let’s look at creating a class for storing calendar 
rlates. Add the Following sexipt lo Listing 2 

script CalendarDate 

- CultindarDatG has three properties day, mouth, and 
year. 

property calendarDay : 0.0 


28 APRIL • 2008 


WWW.MACIECN.Cm 












Network, Server 
and Appliance Monitoring 

C For Mac OS X 




^^fiXserve RAID 


Xsefve (Intel & G5I 


Airport 


Lithium Network Monitoring Platform 

Lithium can now monitor your Xserve, Xserve RAID, 
Qlogic switches,iAirports, Mac OS X Server... 
and everything else in your network. 


www.lithiumcorp.com 















































It has a beautiful touch screen, gorgeous 
fornn-factor and amazing capabilities... 
Our Job is to keep things that way. 

revo 

flevdut>ot\ar>^orQte«ibr ^or yout ^Phorre 



i<t Otswo jJflpda'ttSJ 


Multisession burning reinvented 



BurnAgain DVD 

Multiple Sessions - one Volume. 
Add files to your CD or DVDRW 
several times - without creating 
multiple volumes. 

"BurnAgain is quite possibly the smartest burning utility 
I've seen for Mac OS X...” tuaw.com 


property calendarMonth : 0.0 
property calendarYear t 0,0 

Sets tbe calendarDay property to the value passed to 
it. 

on SetOay(theDay) 

set calendarDay to tKeDay 
end SetDay 

— Sets the calendarHonth property to the value passed to 
it. 

on SetMonth(theHoiith) 

set cal endsrKnnth to theMonth 
end Set Hon th 

- Sets the calendarYear property to the value passed to 

it. 

on SetYear(thcYear) 

set calendarYear to theYear 
end SetYear 

^ Returns the value of the calendarDay property, 
on GetDayO 

return calendarOay 
end CetDay 

• Returns the value of the calendarMonth property, 
on GetHonth(J 

return cal endarHonth 
end GetMonth 

” Returns the value of the calendarYear property, 
on GetYearC) 

return calendarYear 
end GetYear 

on IniLiallEeDatetinyDsy * myMonth, ttiyYear) 

SetDayfmyDay) 

SetMonth(myMonth) 

SetYear{myYear) 
end initializeOate 
end script 


We can i mi tale a c)as.s by creating a top-level function, 
declaring properties for object data, and creating functions to 
set the propertie.s and get their valiies. To create script objects 
derived from this class description, we can use the copy 
command to make copies of the scripts, which will make 
copies of all of the functions and properties of CalendarDate. 
We can write the setup fnnenion as: 

on setUpiJ 

copy CalendarDate to firstDate 

copy CalendarDate to secondDate 

- Set the values for the first date. 

tell flrstDate to InltializeDatatZl, 9, 2007) 

- Set the values for the second date, 

tell secondDate to InitlalizeDate(25. 9. 2005) 
end setup 


Now that we liave two objects (firstDate and 
secondDate) and have initialized them, we ran use liic 
functions of the CalendarDate class to cfieck the values of 
the two objects. 

script I CheckSajneMonth | 

property parent i regig terTest Case (rrre) 
set p to flrstDate*s GetHonthC) 
get d to secondDate’s GetMonthC) 
shouldtp is equal to d, “month not equait**) 
end script 

script |CheckmfferentMonth| 

property parent i reglaterTefitCase(me) 
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set p to ffrstDale's GetHouthO 
seL d to secondDste's GetMonthO 
ahauld(p Is not cqusi to d. "month is the samel"] 
m\d script 


Our i'ini.slicd script nuw lotiks like this (Listing 3)^ 

property parent : load script file 

((“Sylvester tlD:Library^Scripts:") & “ASUnit.a€pt“) 
property suite : maketeBtSuUe("Hy Diite Teste") 

script |DateTests| 

properly parent : ceaisterFiKture(me) 

properLy firstDate i missing value 
property secondDate : missing value 

script CalendarDate 

CalendarDate has three properties day, month, 

and year, 

property caiendarDay * 0.0 
property calendarMunLh : 0.0 
property caiendarYear : fl,0 

- Sets the calendarDay property to the value pss.sed 

to It, 

on SetDay(ihoOay) 

set calendarDay to thnDay 
end SetDay 

- Sets the caiendarMonTh properly to the vaiue 
passed to It, 

on S etMont h(theHon t h 3 

set calendarMonth to theHonth 
end SetMonth 

^ Sole the calendarVear property to the value passed 

to it * 

on SciYearCtheYear) 

set calendarYear to theYear 
end SeiYear 

^ Returns the value of ihe calendarDay property, 
on GetDayO 

return calendarDay 
end GetDay 

— Returns the value of the calendarMooth property, 
on GetMorithO 

return nalondarMonth 
end GetHontb 

- Returns the value of the calendarYear property, 
on GetYearO 

return calondarYeat 
end GetYear 

on InitializeDnLe(i*yDay, myHonth, niyYsarJ 
SecDayCmyDay) 

SetHonth(myMonth) 

SetYearCmyYear) 
end Tnitiall^eDaie 
end script 

on setUpO 

copy CalendorDate to firstDate 
copy CaiendarDnte to secondDale 
— Set the values for the firfit date, 
teii firstDate to InitialIzeDaicCZl* 9, 2007) 

- Set the values for the second date. 

tell secondDate to InitialtzeDateiZ^, 9, 20053 
end .qetUp 

script ICheckSameWonthI 

property parent ; regislerTestCase(me) 
set p to firstDate"S CetHonthC) 
set d to secondDate"s GetHonthO 
shouldCp is equal to d, "month not equal I") 
end script 
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sfript; |CheckBiffftreiitMonth| 

property parent t reglsterTestCase(i3je) 
sot p to firstDate's GetMonthO 
set d to secondnale*S GetManiihO 
shouldCp is not equal to "*Eionth is the same!'*) 
end script 
end sc r Ipt 

run makeTextTestEunnertsulte) 

After adding these tests, we gel die following results^ 

My Dale Tests 

DateTests CheckSaiiifiMontb ,., ok 
DateTestS ■ CheckDlffetentKonth FAIL 

FAILURES 


teat: DateTests ■ CheckBiffereniMonth 
message: month is the same! 


Ran 2 tests in 0 seconds, passed: 1 skips: 0 errors: 0 
failures: 1 

FAILED 

Since lx)th first Date and secondDate had the 
same value for the calendarMonth property, 
the CheckSame Month test passed while the 
CheckDifferentMonth failed (since both niontli values 
were the Sitme). We am add additional lesLs to check the day 
and year values as IVjDows: 

script jCheckSameDayI 

property parent : reglfiterTest Case {dig) 
set p to rirstfiate's GetDayd 
set d to secondDate's GetDay0 
should^p Is equal to d, "day not equal 
end script 

script jCheckDifferentDay I 

property parent : registerTestCasetme) 
set p to firstDate’s GetDayf) 

SGl d to secondDate’s CetDayO 
should tp Is ooL equal to d* **day is the saniG!**] 
end script 

script IChpckSameYearI 

property parent ■ reglsrerTesrCasetme) 
set p tn firstDate'fi GetYearO 
set d to secoiidDate's GetYear[) 
should(p Is equal to d, "year not equal!") 
end Rcript 

script |CheckDiffereniYearI 

property parent : registerTestCaseliae} 
set p to flrstDate's GeiYeart) 
set d to secondDate’s GetYearO 
should(p is not equal to d. “year is the same!") 
end script 


Running all of the tests togeihiT gives the following results: 

Hy Date Tests 


DateTests - CheckSameMonth ok 
OateTests CheckDi f ferentMonth FAIL 

DateTests * CHeckSameDay .*. FAIL 
DateTests - GheckDiFferentDay ok 
DateTests * CheckSameYear ... FAIL 
DateTests ■ CheckDifferentTear ... ok 

FAILURES 


test: DateTests CheckDifferentMonth 

message: month is the same) 


test: Datp.Tests - GheckSameDay 
message: day not equal] 


test: DateTests ChetkSameYear 
mes^sage: year not equal! 


Ran 6 tests in 2 seconds, passed: 3 skips: 0 errors: 0 
failures: 3 

FAILED 

We on see that the test results show that the month is the 
Slime for ihe two objects firstDate and secondDate, but 
that tlie day and ye;ir are not the same. 

To conclude this example using ASllnit, we will show 
how lo separate tlie prt>graiTi code from the test code. Copy 
the script Calendar Date to another file and call it 
Date.scpt. Next, save the above script as DateTe.si.sepl, 
delete the CalendarDate script and add another property 
at ilie top of the script to load the [program code from 
another file. Finally, we need to nuKlify references to 
CalendarDate in the test script to include the property 
added at tile top of the file. After making these clmnges, the 
test script looks like this: 

property parent : load script file 

(("Sylvestec HD:LibraryrScrIpts:"} A "ASUnit.sept") 
property lib : load Rcrlpt file 

({"Sylvester HD:Test;") "Date.scpt") 
property suite : inakeTestSulte("Ky Date Tests") 

script |DateTesls| 

property parent : registerFlKture(me) 

property firstDate : missing value 
property secondDate : missing value 

on setUpO 

copy lib*s CalendarDate to FirsrDate 
copy lib's CalendarDate to setondDate 

- Set the values for the firsI date. 

tell firstDate to TnltlalisiGDate{21. 9. 2007) 

- Set the values for the second date. 

tell aecondDatc to TnitializeDate(25. 9. 2€05) 
end setup 

script ICheckSameMonth) 

property parent : regloterTestCasetroe) 
set p to firstOate's GetHonthO 
set d to secoiidOalc's GotMonthO 
should(p is equal to d. "taqnth not equal!") 
end script 

script ICheckDifferentMonthI 

property parent : registerTestCase(me) 
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set p to firstDate*s GetMonthC) 
d LO GetMonthCJ 

shouldtp is not equal to d. “month in the same!**) 
end script 

script I ChecksameDay| 

property parent : re^ifiterTestCase{me) 
set p to rirsttlaie's GetDayO 
set d to secondDate's GetUayO 
should(p Is equal to d» “^day not equal!") 
end script 

script |CheckDifferentDayI 

property parent ; registerTestCase{iDe) 
set p to firstDate's GetBayO 
aet d to uecondDate's GetDayC) 
should (p is not equal to d, “day is the sumer) 
end script 

script |CheckSapieYear I 

property parent i regi aterTesLCaselniE) 
set p to firstDate's GetYearC) 
sef d to secondDaio's GetYeart) 
should(p Is equal to d, “year not equal I") 
end set 1pi 

Btript ICheckDirfereniYearI 

property parent : re|tisterTestn3se(iie) 
set p to fltsHlaie’s GetYearO 
set d to secondDate's GetYearO 
should(p is not equal to d. “year is the samel") 
end script 
end script 

run makeTeRtTestRutiner^suite) 


Wlicn we am the test .schjn l>ateTL'si..scpi fa>rn die Seripi 
Fxlittjr, we the s;iiiie te.st results as tlie airnbiiied file in ilie hsi 
Mxlton. 

Conclusion 

Using die concepts of test-driven deveiopment, you on 
build and test your application as you go to make sure dial it 
works the way you want. Using the ASUnit testing framew^ork, 
you can create a suite of tests to sers^e as a check of your 
aj^plication logic whenever you make u|Klales. Tlie tests you 
create give you the freedom to refactor your ccxle while still 
Ix^ing able to ensuix* tliat ycnir application works as expected. 
In the second part of this series, we will develop a complete 
application using test-driven development and the ASUnit 
lesiing framework. 
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rter Karl Interactive’s Email Append Services can help! 


The USPS Postal hike has catalogers and vendors justifiably 
very concerned. Now that holiday direct marketing strategies are 
been planned, this postal hike represents a significant addtional 
investment, without supplemental return. 

Over the last five years, many companies have shifted a portion 
of their marketing from print to online and email. With this postal 
hike in place, increasing your online presence is even more 
critical to the health of your business. 

Walter Karl Interactive can help your business by using email 
append and replacing your postal mailing with an email campaign. 

This approach will substantially cut postage expenditure and 
Increase your margins. For those customers that fall off your 
mailing plan because of the time since their last purchase (and 


the resulting lower response rates), there is another option. 

Walta- Karl Interactive can help you reduce your postal 
expenses by providing you with a permission-based email 
address for your customers. You can reduce the frequency of 
your postal direct mail campaigns to these online customers 
Wm-ioUT reducing the frequency of commuracations to them. 

Please contact Dan M. Gabb at 954-66(M)225 
Of E-mail: tiaiLbabb@wkinteractimo 0 ni 
Website: »nArw.AppendSemces.CQfii 

ICAfI ^ Drive, Suite 350 

White Plains, NY 10604 

■■T Tel: 954-660-0225 • Fax: 954-385^10 
Visit us at: www.appendservicGs.com • www.wkinteractive.oom 
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ANIMATE WITH EASE! 




ALL-IN-ONE ANIMATION SOFTWARE 

The only start to finish animation software 
toolset designed for creative and 
professional users. 

• Draw, scan or import artwork into system 

• Paint artwork automatically 

• Lip-sync mouth movements to voice tracks 
•Animate in conjunction with sound, effects 
•Access libraries to use and reuse content 
•Create motion and camera moves in 3D 
•Apply special effects 

• View animation in real time 

• Publish to TV, HDTV, video, web (SWF, QT) 

Teacher's guide and animation lessons available 

toonboom.com 


















Modularity 


Continuing our iook at creating depioyment 
images, with an intro to InstaDMG 


By Philip Rinehart, Yale University 


^ y MacEnterprise.org 

Mac OS X enterprise depioyment project 




MODULARITY 


the MacL‘ntcq:irLst* list has l>een talking quite 
hciivily alHRii a topic from la.st months article: image motlulariiy 
lliis nionilv let’s take a kx>k at new ways of tTcating images, 
hx’iising on a new ttxil from afpS4R.com, InstaDMG. lire idea 
here is dial any image can Ixe created c]ijickly. Is not machine 
dependent, and can lx.* deployed across the tmtire pc)pulation of 
managed machines. 

INSTADMG 

lastaDMG, from afpS48.com. stirrs to address ihe is.sucs ifiai 
we talked iiHmi in previtius ailicles: scalability, mcxlulaiiiy. anti 
flexibility. At its core, a latge shell script drives this .solution, liy 
using a shell script to drive ifie pixxess, it Ls cjuite tntnspjtrent, 
and nm lie eiisily unclenitotKf Tlie Ilrst sief> io fx*gin using tlie 
pr(x*e,ss is to in.strn a retail versif>n of lxx)pard and creating a disk 
iniitge of it. Wait, dtxsn’t the break the ciirtiinal mle of always 
using the disks tliat came with the machine. It dtx'S. bui ixrad 
on, and you 11 Ix'gin to understand why you can break this rule 
with InstaDMG. Al the lime t)f this WTiling, once the dmg has 
Ixxm created, drop it into the BaseOS folder. You can keep the 
name as Mac OS X Install DVD. 

Next, download each installation package from the Apple 
download site. As you arc working off the retail versitjn of 
Leofiard. ciich and every ckjWTiload has to be applied to I lie 
image. 11lis Is where the lieauiy of InstaDMG liegins to come 
through. Take all of the ujxlates. and place tfiem one at a lime 
in individual folders in the ApplelTpdates folder of the InstaDMG 
tree. There is one cuvrai. ortler is imp(>rt:mr for some packages, 
and you will have to know tfiut when you crcalc the tree, Htjw 
do you knf)w? It's a hit of a black art, in that there is iiollting 
that will definitively give you That answer In general, I've 
resorted to taking a lrasc‘ installation, taking a hitse install, and 
applying all .stiftware u|xlates from ilie command littc. f)aying 
allentitm U> order of application. 

After all of the Ap[)le itfxlales have Ixx^n ordered, and 
placed in their correct folders, do die .same for any sofiw'arc* that 


yoLi want to add to the ba.se image. Again, placing tile 
installation packages in folders controls order Note though, ihai 
everything has to lie packaged, as ln.siaDMG mlies on iKring 
driven from the cxxnmand line installer, 'fhese means no VISE 
installers, no Zen>G installers, ntilhing but Apple packages. 
Hoitunaleiy on Leopaai, this task isn’t as difficult as it once was 
dianks to the new Packagemaker snapshot option. Some 
packages may also need to be R^pin'kaged. as they aren't 
installed correctly from the command line. I ran into this slraiglit 
avtiiy, as the CLscoVPN installer is a package, but doesn’t install 
corrextiy horn the commami line. After repackaging, it was 
much happier and did work. 

Automagic 

One of the interesting tilings [lull recently was added is a 
nc^^ lea I Lire for the iastaller in Leopard. It allows for item 
selection clirmly with the use* of i\n XMl, file. How does li work? 
In sim[)le tenns, an xml 11 le is fed to installer at the 
command line, and options are selectcxl or deselected. Dl 
summari/.e an excellent post from Patrick Eergu.s found on die 
alp54H forums. hl!p://www,ofp548.com/Wum/viewlopic,php? 
diawtopic=18907. 

first, nm the installer from the command line in the 
jbllowing way: 

audo insjtailec -showChalCesXHL pkg tity.pKg 

This dumps an XML list showing all tif the choices available 
in any packiige installer. Run this cx>mmand on the OSinstali.pkg 
from an OS X Installation, LtK>k for the xml lag, choicefdentifier. 
Note how they aie formed, they should kxik somewhat similar 
U> the choice,s providetl in a GUI rastallation dialog. 'ITie choice 
should show as Ix-ing selcGed using 1 for selerted or 0 for 
uaselecietL 

Now. create a plain text file, with an array of strings, like so: 
<array> 

ng,>c!hoiceK/strin^) 

<6trin&>chqice2</strin^L^ 

</array> 
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Save iL as an xinl file. One quick noie, you can 
select/deselect options, even nested onevS. hailer the optifin as 
many times as you need ro click the opiion to enable il in the 
Gin. U sounds a hit more conipiiaited than it Ls. After you have 
the xml file, check yum o[)tiuns using the ibll(3wing command: 

sudo iiitiLallt*r ahawCiioit-tisAftcirA[jplyingCh3ngesiXHL 
pk^ oiy.pkR 

Compare il to t!ie first command ulxjve. If the installer 
doesn't reflect the changes that you entered, then your xml file 
is incorrect. How d(x*s this new ability apply to InsiaDMG? 
Creating an lnstaIleKlht>iccs.xnil llle can control die optiijns that 
are installed with the operating system during image creation. 
Place this file at the root level of the clirecrt>ry. Hertfs how' mine 

looks: 

<array> 

<str Jng>Ai1ditioiialFotitE</string> 

<3tring>Xll</string) 

(/array) 

This file installs tlie Acklitional Fonts piickage, as w^ell as the 
XI1 package. Right tK>w, tnstaDMG only deals with an 
InstcallerChoices.xmf file for the Base OS. In ihe fumre, it will 
accommodate xml files for any otlier package that can use 
options, 

Last steps 

Once all of the j'jackages and U[xJates iiave been added, it 
really is simply a marter of ainning the bash shell script in the 
Instai )^^Gl pac’kage. Launch it, and it w ill create an ASR scanned 
image in a rather short [period of lime. Note, the sjx^ed at which 
the image is created is entirely dependent on the computer that 
is creating the image. After the ASR image has l>een created, use 
whaievcT method you have to apply the image to a machine. In 
my usage of tlus pniduct, 1 was able tt) build an image that I 
could apply to a MacBook Air! Pretty dam txK)l! 

One last note this month, even though Fve UilkcxI alx>ui 
InstaDMG, there are other programs that are attempting to do 
similar tilings. You could also use System Image Utility or 
FKGlmage lo do similar things. 1 just find InstaDMG to be 
stiuightforward and simple. Witli it, I no longer Iiave to maintain 
a “build" sheet, and any of my staff can use the process - a major 
plus. Uintil next month, see you on tlic lists! 

Jil I 
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The universal genius 
for picture editing 

■ More than 15 mill Lon uaers 

■ I mport of m £xe tfi 3 n kxj gisphlc formats 

' Export of more tha n So gra phic formats 

- Pictuiie editing 

* Document browser 

' SI foe show and batch processing 

* Edrtingof all mda data (EXIF. IPTt:.XMP_) 

- And much moiE... 

Only $34.95 

{Version in the box $44.95) 


Save 10 % by ordering direct from 
www.lemkesoft.com/mactech 



Grow Your Revenue 

with the 

Edgeos Security Services Platform 


Your expertise combined with the Edgeos platform 
enables you fo provide Security Services to all of your 
customers, building loyalty and recurring revenue. 

Your security services for Your customers: 

• Comprehensive private labeling that enhances your brand 
and provider a aimless customer experience. 

• Simple, jcakable pricing that Is affordable for your business 
and ensures you remain profitable. 

■ Robust scanning engine and extensive reporting to facilitate 
regu tato ly/sta n d ords co mpHan ce. 

• losy to set up. use. grow and manage. You can focus on 
what you do best. 

Visit www.ecfgeQS.com/mactech/ today to view the 
demo and signup for a free evaluatlan account. 
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RubyCocoa 

A new way to write 
Cocoa opplicotions-Port 1 






I admit it. I have a soft spot for Ruby. Tfiai pmlial^ly comes 
as no surprise, if you\^e rend my enrlier articles (particularly 
iulnKluclion Lo Ruby on Rails and Ajax on Rafis; lioth availnhle 
online at KV^T^^.mactechx‘t>m). Needle.ss to .say, Fm quite i^iddy 
with l.eoparcfs scripting language .siippoii. Leopard has elevated 
Python and Ruby to.. .um., not tlrsl class ( ilizeas. Not quite. But 
they make a stmng second-class showing. 

In fact, my l:)iggest complaint comes from the teiniinology. 
Apple’s owm d(K:umentation refers to both Ruby and Pyi:hon as 
.scripting languages. Scri]Hing l^mguages? Sure, they are IkhR 
interpreted languages, but the woai ’'sciipting'' makes iliem 
sound like limited, little things. Lrust me, you oan use these 
languages to do a lot mom than just write scripts. We have two, 
hill-blown, dynamic, object oriented programming languages, 
and [jeopard purs their |X)wer at our fingertips. 

New Ruby and Python Features 

Ruby and Python are not new to OS X. Tiger shipped with 
]x)th languages installed (tliough, if youVe read my previous 
articles, you know' that the Tiger verskjn cjf Ruby kinda .sucked), 
Leotwd, liowevta; kicks the .supixai up a notch. They ve 
invested a lot of time into getting tiie details right. While they 
may not always succeed, 1 appreciate the efibit. 

F(jr example, Xctxle tomes w'itli templates for a variety of 
Ruby and Python projects. Syntax highlighting and ccxie 
completion work as expected. Most importantly, Leopard 
inicgraies hoih langtiages more tightly intc^ the operating .system. 
Both include a bridge to the Ohjective-C runtime, and both can 
communiaite with scriptable ap]:)lications. 

The Bridge to Objective-C 

Leopard ships with the popular RubyCtx'oa and PyObjC 
libraries already installed Developers can use these libraries to 
write Ctxx)a applications in either Ruby or Python, respectively. 
Bcjth languages have access lo Leo[>arcf's core teclioologies, 
including Core Data, Bindings and Document-based 
applit:aLions. These librtirie.s even siip^xirt the new' rock-star 
frameworks like Core Animation. 


But* why would you want to use Ruby or Python? Some 
might say iheyVc addictive; once you slari using ihem it’s hard 
to go back (trust me, 1 use Java for my day jolb. But, yem can 
find other reasons as well. Botli Ruby and Python are very 
expressive languages. You c^an get a lot of work done with very 
little code. This makes them idea! el to ices for rapid 
develoj:>ment and prototyping. 

AddiiionallVj Objectivc-C, Ruby and Python .share many 
comnum ctmcepLs and design choices. They are all dynamic, 
object-oriented language.s. Ruliy and Olijective-C in (lariicular, 
were both heavily influenced by Smalltalk, This common ground 
helps LIS coordinate onr code acToss ihe differeni languages* 

And we can freely mix our code. We can use Rul)y 
siilx'la.s^ses of Objective-C classes, or Python delegates for 
Objeclive-C objects. We can transparently aill one language from 
the other. This gives us more jxiwer and more [lexibility than any 
one language would have t;n its cjwn, We have access to each 
language’s libraries. We can exploit their individual .strengths, 
using one language to s[>acklc over the oiliei s weaknesses. 

Unfortunately, CtK-oa .seems to have a one-hridge-at-a-time 
rule* Mixing either Ruby or ITthon with Objective-C works just 
fine. But mixing Rtiby and Python quickly Ixicomes prol)lernalic. 
Both fnnnewxirks try to load the BridgeSup|>oit dylib, and this 
t an ciu.se erroi^* Some developers liave posted workarounds on 
the web, but they lend to leel rather hackish \o me. Still, I think 
this issue will smL>oth itself out with hiture updates. 

The Bridge to OSA 

We c'an alst> use Ruliy and Pytlujn lo communicate with 
sc'riptahle applicatic^ns using the Open Scripting Architecture 
(C^SA). RuhyCtx:t>a and PyOlijC alreaiiy give us full access to the 
native Sciipting Bridge, but 1 tliink lliis oi'ten !x.*eomes unwieldy. 
We end up wanting RulTy (or Python) versions of Objective-C calls 
on AppleScript APIs. 

Fortunately, eacii language lias irs own libraiy^ lo simplify 
.scripting: RubyOSA for Ruby and py-app!esaipt for Python, 
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Onfoitimatcly, froparil docs noi include tliese libriries. You need 
to iastall thcni on your own. 

Ruby in Leopard 

For the rest of tills a Hide will d\^ into tlie Ruby-spccific 
additions to leopard, Fyilion has coinparibie features, but tor 
simpliciLies Sitkc, 1 will ftxajs on what 1 know. Ruby comes ready 
for .serious development. Leopard's installation inc'ludes several 
iiuporlani libraries: nike, Mongrel, Ferret, Capislnuio, sc[lire3' 
niby^ dnssd (aka Ikinjour) and Rails. Of course, given the fnintic 
rate of Hul)y devekjpment, many of these libraries have alrr^idy 
grown long in the tooth. Still, that’s not a huge concern. Leopard 
also includes RutiyOeins, 

Ri»l)yCicnis is a command-line package manager tor Ruby. It 
allows us to quickly ancl easily insUitl and update Ruby libraries. 
For example, to uixJale the current version of Rails, just type: 

gem upclaie iiicludo dapf^ndenclefi rails 

However^ if you^re like me, the thought of wildly upgciding 
your system libraries m;ikes your stomach churn. Wluit hapfjcas 
if .something goes wrong? Stxjner or later, sometliing always goes 
wrong. Won't this [usl screw u)> my system? 

Well, put down that lx)ttle of Pepto. Uajpard camful ly 
.separates its pre-installed libraries from ilie user-installed libraries 
and updates. Accidentally uf^dating to an unstable version doesn't 
change your original system files, Simply uninstail the ofi’ending 
lil^rary, and you’re gotxJ to go. This also makes rolling back to 
factory defauiLs <|uite easy. Simply delete the user-gem.s hikler, 

Leopard keeps built-in libraries in the 
/System/Library/Frameworks/Ruby•framework/Vers 
ions/l,8/usr/lib/ruby/gems/l-8/ folder. Hie gems 
subfolder contaias the acuial libniries, while the doc subfolder 
contains both rt and html ckKumemaiion. 

When you run gems, it saves iiew^ libraries to the 
/Library/Ruby/Gems/1.8/ folder. Again, you can find the 
libraries in the gems hilder, while d(KHimc^ntation is., ,waii for it. 

. in d(X'. 

Just to lie complete, Leijpard stashes the RubyCocoa files in 
a third location: /System/Library/Frameworks/ 
RubyCocoa.framework 

I liiglily recoimneiid ixiking around in iliea^ directories— 
paiticularly the RubyCcxoa header files. Tliey can give you a 
good feel for the breadth of options 2 ivailalde. 

The Limits of RubyCocoa 

Of course, Uicrc 'dve no silver Ixillets, and RubyOxai hits its 
sliare of downsides. 

Slow^ SlOWj slow 

As much as 1 love Ruby, it is a fairly slow, interpreted 
language. RubyCoc'oa cxxle will mn significanily slower than 
etiuivaleni Qbjective-C ctjdu. Depc^nding on the application, tills 


nxiy not lie a problem. After all, G\ \ af>f>hcaiions spend most of 
thtar time waiting on the user an^^vuy. 

Ikcsides. if a RiibyCcKX>a program fetis slow, you can always 
profile ti and kxik ff>r IxHtlenecks. Once you identify likely 
prohlems, you ciin either redesign your ctxJe to eliminate tlie 
fjoltleneck, or convert it into faster, Objective-C CfKie. 

i'inally, the newly rele^lsed Ruby 1.9 uses a new, faster virtual 
tiuK'hine. llnforLimately, as 1 write tjiis, Ruby L9 only comes as a 
development release—it's nt)t quite retidy for prime time. 

Not thread safe 

Ruby l.H is not tiucud safe. You canntir cjll Ruby c<Kle on 
multiple native threads, lo prevent pKissihle prohlems, the bridge 
actually rerouttes all Ruby calls from ObjecUve-C to the 
applic:alion's main tlaead. However, as we will scx)n .see, y<Ht am 
still use Ruby's tlireads within your Ruby code, w'hich gives us a 
partial workaround. Again, die pnxJucLioii release of Ruby L9 
should fix this. 

Xcode’s debugger does not work 

You t:annot u.sc Xcodc's debugger on your ruby ctxle. 
However, you can u.se Ruby's debugging t(K>ls along with new 
U"tjpard lools like DTrace and insinimenis. Tlii.s Lsn i an ideal 
sr>lutron, but it works. 

RubyCocoa does not support Objectivc-C 
garbage collection 

To me, this was probably the most dis:ippoiniing limitation, 
liul^y itself usc.‘s garl>age collection, Ixtl your Objective-C cxxle 
must continue to manage its ow'n menxtry. Stmiehow this just 
leels wrong. 

Finding Documentation 
and Getting Help 

Apple has included a number of documents and examples 
to lielp you get sumed. You am find the Ibllowing anic les linked 
off the ''Intnxiuction to Ruby and l^yihon Programming Topics for 
Mat: OS X" web page (bltp://devdoper.opple.com/ 
documentatfon/Cocoa/Conceptuol/RubyPylHonCocoo): 

Ruby and l^hon on Mac OS X 

Building a RiibyQ)Coa Appliaition; A Tutorial 

Losing Scri[:jting Bridge in PyOl:)jC and Ruby(XKX)a Code 

The Leopard Teclinology Series for Developers al.stJ includes 
a nice inirodiicLory article at hfip://developer.apple.com 
/leopard/ overview/script! ngcocoa.hfml. 

However, il you w'ant dtKiimentation alx>ut the framcwx>rks 
that Ruhy'Ctxt>a supptMts, prepare fur disiippcjintment. You might 
find a prt)inlsing folder at /Developer/Documentation 
/RubyCocoa. Unfortunately, this only contains a few- files in 
Japanese. The ar:tiial RiibyCtxoa documentatitm is missing. 
F{jrlunaleiy, we cun fix this. . .mote or less. 

You need to download die latest RiihytxKXxt source release 
from hhp://rubycocoa.sourceforge.net. IJnUir the source files, 
then Hio die following coiramnds: 
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tuby Install,rb config 
nihy instftll.rb doc 



Umbrella, sun screen, cooler not included. 
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Hib will CTtratt^ ri and limil dtx iiincnlation for mosi of ihe 
Cocoa libraries supported by RubyCocoiL However, ihc 
dcKiimenuiiion ha*s two small problems. 

First, it does ntx cover all ilie lih^a^i^s ihai RubyCix^oa 
supports, 

Sea)nd, and more importantly, the installer tends to break 
whenever Apple updates tlieir reference libraries. The 
RiibyCocoa team tries to keej> up witli tlie iatesi changes, but 
they are chasing a moving target, llie 0.13.1) release wHl work 
fine for a fresh install of Xcocie 3 0^ l>in you’ve updated your 
reference libraries, it will fail. In liua case, try ihe latest hnild from 
tlie SVN tmnk using the following command: 

svn CO 

https t / / rubycoctia, svn, source* forge. uet/iivnroot/ mbycocoa/tnmk\ 
fsrc rubycocoa 

Don't lie surprised when yon see eirors while parsing 
Apple's documentatioiL RubyQ)cou should still create 
tlcKaimentation for mtm Ciktxi classes. 

Alternatively, you can simply kxik up the Cocoa classes 
directly from Apple’s rej'erc^nce libniry. As we will see, you tun 
eiisily translate m\ Objeclive-C method into a RubyCtxx>a calf 

Hven witli all the tutorials, ininxluctory^ articles and 
ix^ference liliraries, RubyCocoa has a number of dark corners. 
Fortujiately, you can find several oilier resources to help ytm 
miisier RiibyCoccxi—or at least help you a.sk inielligent’Sounding 
queslit>n.s. 

Examples 

Ijeopard's dev^eloper t(K>!s include 40 siimple projects for 
RubyCocoa, You can find these in the 
/Developer/ExaitipIes/Ruby/RobyCocoa directrjry, Tliese 
.siiniples range from old standbys (yet another Cunency Converter) 
to video games. Take some time u> hit>w'se these prr]^as. They 
give you a real feel for using Ruf>yC(xxxi elTectively. 

Web Sites 

While a quick search on Ccx>gle brings up 370,000 matches 
for *'RubyCocoa” I highly recommend two sites: the RubyCocoa 
[irojecl pages at SourceForge.net (http://rubycocoa. 
sourceforge,net/HomePage) and RubyCocoa Resources 
(hitp://www,rubycocoo,com). Hotli provitle a range of useful 
articles. The ininKluc'ioiy lopics help you get started, w'hile the 
advanced topics keep you coming back for more. 

The Last Resort 

The RuhyCbaxi ctjiiimunily has an active mailing list. In my 
experience, everyone Ls helpful and kind. Bui, plc*ase: don’t 
wuste their time. Try to research the Issue on your own, llien, if 
you're still stuck, dieck out RubyCocx>a Talk, 

You can sulmril'ie to RLihyCtK'oa Talk at 

https://lists.sourceforgemet/lists/listinfo/rubycocoa-talk. 
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Aqua Connect Terminal Server is the only scalable enterprise 
grade solution that allows the Mac OS X platform to be 
deployed to multiple diverse devices, including Macs, PCs, 
and thin clients. Aqua Connect offers a feature set that truly 
simplifies OS X administration. 
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Our Project 


Installing the Gems 


To really understand something, someiimcs you need lo just 
jump in. Tticrcfore, the rest of this article, vv'ill Ibcus on building 
a simple K$S reader using RubyCocoa. 

Why another RSS reader? Leopard already comes with built 
in RSS features for Ixjdi Safari and Mail, not to mention many 
third-party applications. Stilly 1 wanted to try something a bit 
messier than the typical toy project. By tackling a problem with 
rough edges, we get a lx.llcr feel for RubyCcKXia's siiengdis and 
weaknessOvS. 

Addiiioruilly, I wanted a project tliat would demonstrate the 
following four points: 

The project should use a RubyGem library. 

'Lhe project should use key Coc'oa technologies, like Core 
Data and Bindings. 

The project should use RubyOSA to communicate with an 
existing, scriptable application, 

The project should be implemented entirely in Ruby. 

Our RSS retider will read and parse RSS feeds using the 
Feedlbols gem. 1he application will use both Cxire Data and 
Bindings extensively. In part 2, w'e will strnd encltxsures lo an 
iTuncs playlist using RubyOSA. And, except for a single 
Ol>jective-C class, we will only write Ruby code. 

3.8S9 out of 4 Isn't bad. 


First, a c|uit:k word of warning. Don’t update RubyGcins oi‘ 
any of your libniries just yet. As we will see, this may complicate 
things. Notliing we canT fix, but you might want to avoid 
pn>bleins witen you can. 

RubyGems is a powerful package manager for Ruby 
libraries. It is also a complex, command line tool. A hill 
explanation is Ix^yond die sc:ope of Lliis article, l)ul the table 
below should get you started. For more infonnation than you 
could ever possibly w^ant, check out the RubyGem manuals at 
http://mbygems.org/. 


Command 

gem 

man gem 


gem help commands 

gem help examples 

gem help 
<commancl name> 


Result 

Displays l^asic usage 
infonnation. 

Displays the gems manual 
pages. Wliile somewhat lacking 
in details, it does mem ion a 
numi jer of other interesting 
utilities (like gernlock and 
gemwlik'li). 

Displays a list of gem 
commands. 

Shows examples of commonly 
used commands. 

Displays information alioot a 
.spec ific command. 
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DOCKING STATIONS FOR APPLE COMPUTERS 


Convert your MacBook Pro®, MacBook®, or Power Book® 
into a desktop in seconds 

without misplacing cables or damaging connectors. 



Aluminum Plate helps in cooling of notebook 

Connectors are routed to rear of Dock 

• MagSafe® Housing prevents 
■HI accidental disconnect 


MacBook® Pro 
Docking Station 


13.3** M 
MacBook®^ 
Docking Station 








Also availabiO In Black • Built In DVi/VGA full size 
5 USB 2.Q compliant ports • Gigabit Ethernet R|45 

(4 port pDwered or yn|H>wered hub, J 

AC/DC adaptor Included) 


15.4** 

MacBook® Pro 
Docking Station 


PowerBook® G4 
Docking Station 


PowerBook® G4 
Docking Station 


PowerBook® ^ 
Docking Station 


Visit our website for latest product announcement www.BookEndzdocks.com 


Manufactured by Olympic Controls 
1250 Crispin Drive • Elgin, lllinais 60123 • USA 
Phone: 847-742'3568 • Fax: 847-742-5686 • Toll Free: 888-622-1199 
E-mail: Sales@BoQkEndzdocks.com 










gem install <geni nam€> Install tlie named gem. 
gem update 

—include-dependencies Updates all in.stalled gems, 
gem update <gem name> 

—indude-dependendes Update just tlie named gem 

and its dependencies, 

gem uninstall 

<gem name> Removes die named gem. 

Note: many of tliese coinniiinds (especially install, update 
and uninstall) requite rfx>t acces.s, Vou typically launch them as 
sudo commands. 

Also, 1 delilxiately left one coiiiiiiand off the list: gem 
update —system. 'Jliis ufxiates the KuhyOem system itself. 
Unl'ortunately, unlike the oilier gem uptbtes, ihts aciually 
changes your system files, and iliesc^ changes are noi easily 
undone. 

I strongly reconiiiiend leaving tills command alone, Ijei 
Apple manage the RuhyGems system. As Tm writing tJiis, drey 
just updatc*d RuhyUems as part of ilie 10.5.2 release, so it should 
slay reasonably current. Modify the gems as much as you want, 
but leave tile system alone. 

Most of the time, you will use sinifrle install and iijxlate 
ctrmmands; however, tlic others can come in handy when things 
go wrong. U|xlates do not always prexeed as snicxahly as 1 
would like. S<rmetimes they leave a gem or two behaving badly. 
I often find that uninstalling and reinstalling the offending gem 
(and fxjssibly iis deixndencies) sorts things out, 

Now^ that we understand the hisics of KnhyGems, our first 
step should lx the .simplesi. We just need to install our ]>n>ietts 
RubyCtem libraric^s. In tlicxiry, tliis should only requia* typing the 
following command, entering password when pnmiipietL 

Biido gen install 

Untuilunalely, life fs never this easy. Tlie Fc'edTouLs lihrajy 
c'ootaias die depa'CaLcd ruby-gem armtnand. As lung as you’re 
still running the version of RubyCiems tlitit aune witli U-opurd, 
you shouldn't have any problems. The library jusi logs a few 
warnings to the console. However, newer versions of RuhyGems 
no longer recogni?.e this tomnitind. Bottom line, if yoiiVe 
updated to U).5,2, you have the new version of RubyCieius, and 
the FeedTools library will crash. 

Tt» fix tills, you simply need to edit feed tools .rb. You 
can find this file at /Library/Ruby/Gems/l,8/gems/ 
feedtoolS“0.2.26/iib/feed_tools,rb. Globally replace 
**axjuire-gem" with “genf. 

Creating the Project 

Now; wr can create our projea. Open Xcode, and Iront the 
nie menu seleti New Project,,,. In the Assistant wimlow^ scroll 
down and select Cocoa-Ruby Core Data Application. Click Next, 


o 


New Project 


Cocw OOft 04ti Apudiiwtten 

Con* Duid DKUtntHnl - l»ied Appficdlwn 
Coc:cd-l*VCHa!i -b2$|hd ADpHutibK 

Coou-Rutty CjQTG DOIa Oocum^l tta»^ A^>£UA1 
Cocoa ^ Ruby EJoct*mtfi-&iiiib ,*b0Hc«ion 

Con* Oata A|iolrriitiQn 
Qve OatJ DoCurnetTt t»Wi| 

Coc£ Data Docutvw-rvT.-tujAd AjutrilcaTloci wtiti imponci' 

QuATtx ConipDlcp ApplKAtion 

---—- 

This project builds a Cars Data appMcotion lurdtcn Fn Rohy. 


f Cancel ^ FfiViOiJi i (- 


Creating our Cocoa-Ruby Core Data Application 

Fnter RubyRSS for the prtjjett name. Set the project 
directory to wiiatcver you wish. Click Next again. Abmcadabni. . 
.projea created! 

But, lets take a cjtitck kx)k at whai Xaxle has done. 
MainMenu-nib and 

RubyRSS_DataModel. xedatamodei are .standard hies for 
any Core Data applicalion. The fust defines our user interface. 
The secxiod defines our data model. We will take a closer look at 
Ixiih in just a second. 

Ojxn main,m. 'lliis Ls the starting point for our application. 
As you can .see, a RubyGx'oa application's main simply imports 
the RubyG(X-oa runtime, llien launches rb_[nain.rb using the 
RBApplicationMain( > function. 

mmn.m 

Ifimport <Cocoa/Cocoa.h> 
i rapor t < Ruby Cocoa / RBRun t imc, h> 

Iru ntalridiit arge, const char ’arj^vtl) 

[ 

return RBApplicationMain(*‘tb._Jj»ain,rb”, arge, argv); 

) 

Qui' Ruby code really starts with rb__main,rb. The default 
implementniion loads the Ruby Cocoa library, kxaies the 
applicai ion’s resource patit, tjjen loads any files ending with .rb 
using Ruby’s require!) methcKl. 'IItLs cittafes all our Ruby 
classes. Once finished, rb_main,rb calls 
NSApplicationMain! )^ wliidi inilialixes and runs the Cocoa 
application. 

require "oss/cocou* 
def rb_main_init 
path = 

OSX: tNSBundle,mainBundle.resourcePath,f ileSystemRepre^encai. ion 
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eSellerate. Complete. 

Begin defining your strategies at http://www.esellerate.net/mactecK 



eSellerate, the same team that brought you Installer Vise. 

eSellerate is a registered trademark of MlndVlsIon, Inc * a Digital River Company. 
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Merlin 2 


Project 
Management 
with 
a bit of 
Magic! 


Just three out of hundreds of features: 


rbfiles - Dir.entriesCpathJ.select I|x| /\.rb\z/ =* x] 
rbfiles ■= I File.basenaneC_FILE_) ] 

rbfll^fl.eacb do |path| 

requiret File.baseTiaia^Cpath} ) 
end 


if SO — _FILE_ then 
rb_iitaln_irilt 

OSX. NSApplicationMaiii (0 * n 11) 


With our Ruby cbsse*! now cictmcd, we can access them 
fmni Objective-C. Unfortunately, we cannot directly import Ruby 
classes Inio Ot>jcctive-C Ales; however, we can intUrectly access 
the classes by name. While we won’t do this in our application, 
tlie fallowing code snippet shows the iKisic technique. If creates 
a MyRubyClass object dcAncd in a MyRubyClass.rb file. It 
then calls tlie objeefs niySampleMethodCalI(). 

Ruby from Objectivc-C 

Class loyRubyClass = NSClassFiroiiHL ring(ft**HyHubyClass"): 
id ruby = [['^yRubyCIaRs allecl init]; 

[ruby mySarnpleNi^thodCallJ 


Network-based Project Management 
^ Collaborate with others on the same 
project over the network. Just with a 
single mouse click. 


Automatic sync to iCal 

Sync your projects to iCal and then 
^ onto your iPhone or any other 
mobile device. 


Professional Cost Calculation 



Define Budgets top-down or bottom 
up and compare them to planned vs. 
actual costs. 


ProjedWizards 

Merlin 2 is built from 
project managers for 
project managers. 


Get your free demo version 
www.merlin2.net 


Notice how RubyCocoa seamlessly Iran slates oljjects 
Ix^tween Ruby and Objective-C. Usually, you won't need to 
worry, things ju.si work. 

Scxxier or lalcr, however, you will nib up against one of the 
nmgher edges. For example, HubyOK-oa con veils Ruby objects 
into Objective-C equivalents when jxi.ssible. Tliis meaas you can 
pass Ruby Strings to Oljjective-C methcxls. Rui>y€(K:oa will 
aiitomalically convert tiiem into NSStrings. 

However, the reverse is not true. RubyGxoa will place a 
Ruby wrapptT around Ol>jective-€ chisses, and will sometimes 
add convenience melliods (like adding each() to NSString, 
NSArray and NSDict ionary), I nil it does not convert the 
classes. 

So, if RuJiyCtxioa calls an Ohjective-C method that returns a 
string, the Ruby code will gel an NSSiring, not a Ruby String. A 
quick call to to_s{) Axes this, but it can cause bugs if y<nfre 
not careful. Also, Rul>y and Objective-C .sometimes have ven^ 
diAerenl ideas about btxjleans. We’ll lake a ckxser look at that 
little wrinkle later. 

My advice, ignore obieci conversions until they cause 
problems. Tills is Ix^st dealt with on a case-hy-case basis. 

Finally RubyRSSAppDelegate^rb acts us a Kuby- 
implementeri delegate for our application. Feel free to poke 
a roll ml this Ale. However, youll find the most tniencsiing bits at 
the very liegiiining. 'lliis class not only imports the Core Data 
framework, ir also subt lasses NSObject. lliLs just demonstrates 
ht>w e;isily Ruby and Ohjective-C axle cm mix. 

RiibyRSSAppDe(ej;att. rb 

This Ruby code imports a Cocoa framework, then 
subclasses an Objective-C object. 

require ’osx/coeoa’ 
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OWC*^ Mercury Rack Pro 
4-Bay 1U RackMount 
Storage Solution 

^deal for appHcatFons requiring high data 
throughput availability, and flexibility 
in configuration. 
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Bus Powered 
Portable Solution 

Safely and conveniently transport large 
amounts of data with r^o AC adapter needed! 


50 GB to i20GB from 


ffl Hardware RAID, SuftRaid, JfiOO options. 

9 Available with eSATA, FireWire 800/m and 
USB 2.0 interface support 
9 User tusTomizable configurations. 

9 Up to 4.DTB of performance storage. 
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9 Up to 31MB data buffer with data transfer rates over ISDMfis! 

9 Ultra-protective shock isolation system. 

9 Premiere BONUS utility software included- 
9 Available with eSATA, FireWire 800/400, and USB 2.0 
interface support 


9 FWfiOO/400/USB1.0to US8l.0/eSATA solutions. 

9 Fully suitable for audlo/video applications. 

O Super quiet operitiory with shock isolation system. 

9 Premiere BONUS utility software included. 

9 Compact 3.5''(W] % S.5 "(D) i T'lH) siie and weighs less 
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QSX,rtquite_franie¥ork 'CoreData' 
class AppDelegate C OSX::NSObjecL 



Defining the Mcidel 

Built ling a Cf>rL* Data model is lK*yond the seo|>e of this 
artide. For more iiilbniiation, take a kxjk at the G)re Data 
Tutorial video 

{hirp://devel(>perapple,ec>m/et>eoa/et>redatatutonal) t>r Apple’s 
arlide on ereatiiig managed object models with Xeotle 
(http://developerapple,cani/documenration/C>K:oa/Coneeplual/ 
CfeatingMC)M WithXctxle), 

For simplicily's sake, lets import our model from the online 
sotirce axie for this article. download the source (^<xle from 
ftp://ffp.inaaechxom/src/. Deleie RubyRSS • xcdatamodel 
fn>m your project Seica Atso Move to Trash when prompted. 
Tlien. seleci Project fi Add to Project.,., in the hie dialog, selecl 
RubyRSS.Xcdatamodel from the ,sc>ur e ctxle’s folder. Pre,ss Add. 
In the oexi dialog, make sure Copy items into desigrtation 
group's folder (if needed) is selecied. Click Add ag;un. 

Now, open RubyRSS.xcdatamodel, and lel’.s poke 
an>und inside. RuhyR.SS uses a simple nuxlel with only three 
Hniiiies: Feed, Ftjsl and Enclasure. 



RubyRSS's Data Model 



The Feed entities irpresent our RSS sulisaiptions. Feed lias 
ihiee allriliutes: name» url and count. It also has a tc,K>-many 
relationship with Post, 

Past has two artributes: liile anti text, Vmt also has two 
relatitmships: one jxnnts back to Feed, while a tn-many 
relationsiup points to Hnclasttre. So far, so g(x>d—this isn't 
exactly rex^ket science. 

Finally, Fntrlosure has iwtj aiiributes: url and isAudio. It also 
has a single relationsltip with Po,st, 

rhe attributes have stniighiforward tiaia tyjK‘s. I’ve listed the 
derails Ix^low, Inn noihing should ct^iiie as a suqiiise, Als(>, tf you 



OvolabPhlink4- 


Multiple voice mailboxes. Personalized greetings. Full Mac OS X Integration. 



Ovolab Phlink is tbe ultimate message 
cervtef Ibr your Mac It answers phone calls 
and identifies callers using Caller ID and 
Apple's Address Book. It greets your friends 
with personalized messages. It records and 
stores messages on your computer - and 
evert forwards voicemail to email. 
Featuring multiple voice mailboxes, 
call screening, Spotlight searching and fax 
capabilities, Ovolab Phlink makes your 
telephone part of the digital hub! 
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And you can fully customize Ovotab Phlink 
to do exactly what you need, using 
AppleScript: even set It up to call you back 
on your cell phone when important clients 
leave a message. 

Check it out at www.ovotab.com. 
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kx)k curcfiilly ui the mtxlel, you will see that IVe placed some 
resirictiims on the data. In general, I recommend making your 
data as restrictive as possible, liuwever, we doti't need data 
validation tor this tiitorial, so I'll let you explore it on your own. 

Feed 

name String 

url String 

count Ini32 

Post 

title String 

text String 


Enclosure 
uri String 
isAudio IkK)l 


nncltjsiire attd Ft>si are lx>tli NSManagedObjects. 
[It>wever, Feed’s count attribute needs a bit of special attentron. 
Q)unt represents the numlxT of posts assfx iaied with this feed. 
To get this l)ehavior, we will need to sulxiuss 
NSManagedObjects and ovenide the count () accxessor. 

Now, as 1 .sard earlier, 1 hoped to implement everything 
using Ruby. This will lx: the one exception. Trying to write this 
in Huby just creates problems; the default AppDelegate 
implementation automatically create.s Key' Value Gxling (KVC^) 
wrappers for any aLtribyies declared in the 
KSManagedObjectModel. Since this cx'ojrs after our classes 
have Uxicletl, our custom count () method gets doblx^recL 
We <x)uld fix this, but it's easier to write ManagedFeed in 
Objective-C, and Fni all alxjut the pragnuiic. 


Managedi-eed.b 

This is the heacier file for our ManagedFeed class, 

tflDiport <Cocaa/Caroa.h> 

^intp.rfacf! MflnagedFeed i NSManagedObject I 

I 

- (ini:] count ; 

@end 

ManagedFeed. m 

This is the implementation of our ManagedFeed class* 

# i mpo r I “Ma na ged , h *' 

dlmplctnctnailofi ManagedFeed 
+ ENSSet*) keyPaiKsForValuesAffecLliigCoutit I 
NSSei ‘uei - tsuper 

keyPathsForVaiuesAf fectingVa lueForKey; S'*post s" J; 

riturn Iset setByAd din gObj ec t;@“pas t s * J: 

I 
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'{int)count ( 

id posts = [self valueForKey:®''posts”] ; 

NSArray * all [posts allObjects] : 

return [al] coLmt]: 

@and 

You can Find a detailed description of the 
keyFathsForValoesAffecting<key> rnelliod in the 
NSKeyValueOliiserving protocol reference. Essentially, this 
mclhod dcscrilxLts ihe dependencies for a given key. KVO uses 
this to detennine if and when llie key may have dianged. In our 
code, count could change whenever the value of the post key 
changes. We could specify this by just retuming a set tli^it 
contains li"post". 

However, our iiuplenientation is a little more complicatc\l. 
Apjile recommends requesting an initial set of keys from the 
super class, then appending your own key patlis to ilm set. In 
this Uitorial, the call to the sutler class will always returns an 
empty set. I lowever, this implementation protects us from lliture 
changes. 

In the count method, we return ilie number of posts 
associated with tliis feed. We get a cxj|>y of the jxjsts relationship 
using KVC . Then we extract an NSArray containing the,se [X>sis. 
Finally, we return the numlxT of objt.ris in our USArray. 


Building the Controllers 

Apple now recommends building your controllers lx.Tore 
designing your interihee. You am still create controller objects 
witliin Interface Buikier and then export them back to Xcode. 
You <'an even exp(m yotir conirollers in Fhil)y and Python; 
lK)wever, 1 could not get tlie resulting code to am. Best to follow 
their advice and just write the cx:)ntrollers yourself. 

Just like the standard Objective-C versioas, our Ruby 
controllers combine outlets, actions and pt)ssibly a few helper 
functions. Gullets represent liie ITT elements that we will need to 
programmatically interact with. Actions represent Ul-driven 
evenLs. 

Fortunately, RubyCocoa providers an attr_acaessor-like 
method for defining outlets. For thase not familiar with 
attr_accessor, it takes any number of .symbols, and craites 
an iastaoLX* variable for each one. Attr accessor also creates 
the getter method <syinbol>() and the setter method 
<syTnbol>=( ). For example, attr_accessor : name creates 
@name. naine() and name=(). 

Similarly, ib_outlet takes a comma-separated list of 
symbols. Ir converts each .symbol into an instance variable with 
the same name. A eorres[x>nding ouilcM wifi also appear in 
Interface Builder 

Note: you should avoid using attr_accessor in your 
RiihyQx'oa ccxle. Unfonunately, attr_acGessor does rioi 
create KVC compliant vanubles, so we canntX connect to dtem 
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Lusin^ Tlie works 11 nu, Ixit Ctx;tja uxpccLs a 

set<Synibol>() setter {setName() in our example). 

Fonuniiiely, KuhyCcx'oa provides kvcaccessor. 
Kvc_accessor works idcnlically lo attr_accessor, but 
creates KVC ccjmpliant methcxls. 

l^uhyCtx'oa also simplifies declaring KVC dependencies. Ihe 
kvc_depends_on ( ) Mieliiod lakcsS two parameters: an array of 
symixds representing the dependencies, and a single synilx)! 
repixcsenting the calculated attribute. 

Basically, tliis method replaces Objective-C’s 
keyPathsForValuesAffecting<key>(). Take a kxik at 
our ManagedFeed.m file again. The 
keyPathsForValuesAf feet ingCount methtxl defines 
count's dependency uf)on posts. In Ru[>y, we could re()lace tl iai 
method with a single line: 

Jtvc:_depends_on( [:poBts] , :count) 

Finally^ KvibyCxxoa elegantly handles actions. Simply define 
a method wiili a single parameter, usually namcxl sender. Afier 
the method, add a call to ib_action{) passing in the nietlKxrs 
name as a symb<.>l 

Sample RuhyCocoa 

def myAction 

end 

ib_^ctton smyAction 


Now, the Riibyists out there have undoubtedly noticed that 
the RubyCocoa fomiattiiig kx>ks a bit odd, Mtxst of this crce])s in 
when we translate Objective-C syntax into Rnf>y. 

Objective-C's .syntax uses both named arguments and 
ajk)iis—neither of w'hich translates nicely. Therefore, when 
referring to an Objective-C methexi, concatenate all the pieces of 
its signature, and replace the colons with underscores, 

[canvas print: text withFontColor: red]; 

becomes 

catives,print_w.l LhFontColQr_(LcxL, red) 

As a bit of ,syntacdc sugar, RuhyCocoa allows you to drop 
tlie final underscore. 5k), print_withFontColor_() Ixx'omes 
print_withFontColor(). Note: the Ruby arui Pylbon 
ProiJramming Topics for Mac 05'X article claims that tills option 
is disiibled by detauli. Tliis is not inie. In most cases, you can use 
the two variants interchangealily. Tlie exceptions, Itowever, can 
causes real pain. 

Whi^n Ohjective-C: nills a Ruby meilKHi that overrides an 
Ohjective-C method (Ah, yes. Site knows that I know^ Lliai slie 
knenvs that 1 know. . . J, RuhyCocoa looks for tine method 
signaiitre wlthottt the traiiing underst'ore. So, just to prevent 
pnssil)le problems, I recommend iiniversally dropping the last 
underscore. 

For a>risistency, I ve tiiet! to use camel case for actions 
(likeThis). Piire-nthy helper functions have the moTe-tr^iditional 
underscore names (likejhis). 
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OK, enougli babbling, ItMik at tlie code. We will liave 
twx) winciowN in our Hb the main window, and a dialog Tor 
adding new feeds Ix.n’s ereale a coni roller for each: 
MainController,rb and AddFeedControiler.rb 
resjXNilively. 

Ma in Controller, rh 

This class acts as the controller for our main window. It 
Responds to all the main window's actions, and makes 
changes to the data model. It will also coordinate with 
both the heed Tools and RiibyOSA libraries when 
necessary. 

require 'oex/cacoa' 

# Com roller for the Main window, 
class MainConTrol1cr < OSX;:WSObject 

ib^ciiiLlet :feeds, iposis, lonclosurea* :wob_v1ew. 

:poste .table. 

reut:losures_Lablep :progrof^s. rapp_delegare 

^ accessor Cur ihe current Feed cellection. 
def feeds 

re turn @ree<is.arra!igGdObJi!Cls 
&nd 

4 Add remaining methods here 

end 

Here, we're tiuilding a sutxiass of NSObject. We start by 
declaring a slew of outlets for Interface Builder. Hie feeds (} 
accessor returns an anay containing all tnir Feed enliiie.s, I'his 
re[irescnts all cuneiitly .siibscritxd feeds. 

Ihe next two meikxis override NSObject inethfKls. Hie 
Qx'oa franiework will aiiToniatically ( all these, 

SSOhject Methods 

Jf InitialIzefi the Main Window after it is loaded from the 
NIB, 

def awakeFrouiNib 

^P ■"t>£I"P^ 1 ^ 1 ^ i f:p 1 ay ed WhenStopped {f alse) 

§posts.addObRerver_forKeyPaT.b opt ions context (self ♦ 
“selection", 

0, nil) 
end 

// ThlJ3 listener method will be called whenever the Post 
Table's selection 

# changoa. Tt Lipdaies the HTMl, In the web view, 

def observeValueForKeyPath^ofObject„change_context( key_path. 
object, 

change, context) 

set_html if @posts.isEqual(object) 
end 

Tlic franiework calls our awakeFromNib () metlKxl aftcT 
all objects have been loaded from the nib tile, and once all 
outlets are set. We can use this meUiod to pcTform any additional 
initialization. In our case, we make the 
NSProgre S3 Indicator invisible when not in use. We also 
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force our conrroller to listen for any changes to the i posts 
selection. 

The framework now calls 

observeValueForKeyPath_ofObject_change_context 
() whenever @ posts's selection changes. We simply verify that 
weTe receiving an update from @posts, then call the 
set_html () helper methocL 

Note: As 1 mentioned earlier, you must drop the final 
underscore from tliis metlitxi's name. Odierwlse, Key Value 
Oba-rving (KV(J) amnot find our implementation. 

Next, we declare two aciions; sendToItunesAction<) 
and refreshFeedsAction(). Currently, they ju,si print a 
message to the coasole. 

This action sends the currently selected Enclosure to 
iTunes* 

def fsendToTi tmeBAct Ifin^Render) 
puts “Send to iTunes" 
end 

lb._act 1 on : snndToi t unesAr t i on 


I? This action refreshes all the feeds, 
def refreshFeedsAciioij(sender) 
puts “Refresh Feeds’* 
end 

ib^acllgn ?re£reJjhFeedsAciion 

Add_f eed () adds a new Teed entity to the managed (ibjea 
context, ft then fills in the feeds attributes. NtHice that it leaves 
the jx)SLs relatitniship blank. We don’t have any ptxsis yet. 

addJced() 

S Addn a new feed to the Managed Object Context 
def add_teedtnane, url) 

moz “ #app_delegute.nianagedObjGctContext 

new^feed = OSX:iNSEntityDescriptionV 

. insertNewOb jectForETitiTyForKarae_iiiHaiiagedOb jeetContext (“Feed * 

tiiQcJ; 

new^feed. setVaIue_fDrJ(ey(naiiie. "031316“) 
new feed,setVHlije_forKGy(url * “(irT’) 

end 

Finally, set_htmL() gets the text from our ciirrently 
selectex-l [xxsi. We tlien display tliis text in tmr web view. 

sei^htmlO 

private 

(f Helper Function: Updates the HTHI* displayed by the Web View 
to the text 

tf of the currently selected post, 
def aet_htiil 

indax = #post Salable .selectedRow 
frame “ #web_view,malnFrame 


# Tf nothing Es selected, just recuru. 
if index < 0 then 

frame, I oadHTMl^St r i ng^ba^etJRU (“ “, nil) 

else 

post ~ ftposts.arrangodObjocisllndex] 
frams. loadHTMLS t r iEg_,ba s eURL (post. text, nil) 
end 

end 

Our second conlniller is even simpler. ITiis i:ontn>ller has 
only two outleis, [^lus two KVC-compliant jin>f>erties, and a tliird 
vifuial property. 

The sheet outlet provides access to the Add Feed dialog 
sheet, while the window_controiler provides a link Ixick to 
our m;iin controller. 

The name and url properties hold (not surprisingly) die 
name and URL of the new feed. 

Finally, the virtua! property, valid_feed, returns true if the 
feed has a valid name and URL Obviously, valid_feed 
dejiends ufK)!! the name and url pixjpenies. Key Value 
(.)hserving will call oisr valid-feed accessor wlienever either 
of the dependent variables changes. 

AddFeed€ontrollet.rb 

require ‘osx/cocoa* 

H ArtdFeedController acts as the controller for the Add Feed 
sheet, 

cl^na AdriFeedCont rol ler < OSX riNSflbjecl 

lb„tiuilci ;sheet, iwlndow_con(.roller 
kvc accessor :name, lurl 
kvc_depencis_on( [:nflnin* lurlj , :vnHd_f 0 ed) 

i Add methods here 
end 

Itie open_dialog( ) medaxl ojxais the Add Feed dialog. We 
daiare this as an atiion, so dial wc can link if to a butfon on the 
main window. 

<ipef$_diafog(J 

fl This action opens the Add Feed sheet, 
def open_dialog(sender) 

OSX::H^App,beginSheet_raodalForWlndow_niodaiDelegate_\ 
dtdKndSRlector„contexTTJ3fn( ^sheet - 

f^iaaju_w1ndciw, 

self, 

nil. 

nil) 

end 

ib_action ropeu_diaiog 

Next, we add our add_feed( ) action. We will link this 
ac tion ro the Add button on (he Add Feed dialog sheer. This 
tnetliod .simply ajnverts llic feed natne and URL into Ruby 
Strings, then tielegates back to the main window' controller's 
add_feed( ) method. Finally, it closes the Add Feed sheet. 
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mlii 

f The add_feed actioft ^rabs the name and url from the Add 
Feed sheeL, 

# adds the new feed to the Hanafted Object Context, then 
cloeee the sheet. 

def add_f©ed < send e r) 

feed name * @nam©.to s 
feed^url “ @url.to_s 

#windaw_controller. add_reed (feed^name. feed_tirl) 

cloee^dialog, 

end 

lb action radd feed 

The cancel () action simply closes the Add Feed dialog 
sliceL We will link this :ic:iit>n tf> ilie Cancel hutitsn on the Add 
Feed sheet, 

canceiO 

# The cencel action closes the sheet without adding a new 
feed. 

def cancel{sender) 
close_dialog 
end 

lb_action tcancel 

"Hie valid_feed() incihod uses Rul^y’s regular 
expressions to filter out invalid entries, liasiailly, the feed name 


must contain at least one non-whitespace chaniner, while the 
URL must start with Teed://"* then contain one or more 
characters, a }>eriod, and end with one or more cliaracters. Tlie 
URL cannot have any wliite space. 

Note: While Rtiby has explicit true and false valuers, it also 
tieais all nil values as false, and ait non nil values as tnje. This 
meaas, ilie result of ANDing together two regular expressions Ls 
either nil or the String niatcheil by the sea>nd regular 
expiession. While Rulty will etJrreetly inierprei this as a bcxjlean 
value, when we pass it to the Cocoa framework, we get tlie 
f( >11 1 yw \ ng exet* pt i on: 

AddFeedCoiitroller#rbSetValue_forKey; OSXi:OCException: 
NSInternallmconsistencyException * Cannot create BOOL from 
object <RBObJectJ Oxl437bddO> of class RBObject 

Tci prevent this, we explicitly convert our re.sylt to a h(K>leiin 
value. 

iHtiidJeed() 

valid_feed returns true if the Add Feed sheet's current 
name and url 

if values are valid. This method can be lonltored using KVO. 
def valid_feed 

namo ” ftn.'imo. rci_3 

url = @uri.to_s 

result = name.matchU\S+*) && 
url .marcht ‘ '' rced://\S+\ .\S+$') 
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# i^Xpllcitly convert to booleans. 
return I result.nil? 
end 

Finuily, the private helf?er fuiicritm, close_ciialog() 
clears the Text Fields and doses the dialog. 

close_dialog(J 

private 

# Helper Function: close„diaiog clears the Add Feed's 

# text boxes, then closes the sheet, 
def close_dialog 

setUtK'"*! 

@she et.e rd ei Qu t(self) 

OSX::NSApp.endSheet(esheet) 
end 

Building the User Interface 

Building the user inTertare is also lieynnd ihe scope of this 
artide. Simply copy MainMenu.nil> from llie online source ade. 

Our user interfate consists of the main windcjvv and the Ailti 
I'eed panel. We have three array ccmirollers. 'Hie first a)ntaias all 
of our Feed entities, 'llie set'ond contains all Post enitiies 
associated with the currently selected Feed. The third contains 
all Enclosure entities asscKiated with our airrently selected 
Post, Bindings auioinatit'ally niaijUain ihe.sc relalion.slii|)s, 
R‘(|uiiing no nxle on our part. 

Pinally, we have the Md Feed and the Main controllers 
defined in the previous section. 


contains URLs from die Enclosures army. Again, we set all of 
thesi^ values using Biniltngs. Of these, only the feed nanics arc 
edilahle. 

Tlie Main windt)w also has a Web View'. Tills contains the 
text for the currently .seleaed po.st; how^ever, unlike die Tatilc 
Views, we cannot set die Web View’s content using Bindings. 
Instead, we actually have to w'rite code. 

'lire gcKKl news is, you’ve already WTitten thi.s code. l^K>k 
biK’k at our main controller. Reinemlx.T, how it receives 
noLilK:ations whenever the posts' selection changes? It then 
fires the set_httnl () helper fimetton. ^lliat’s the code w^e need. 
We use KVO to automatically synchronize our wel> view w^idi the 
current selection. Basically, we’ie rccic-ating die code that 
Bindings normally gives us for free, 

Finally, our main window lias four Buttons: one adds a new 
fetxi, cme deletes the selected feed, one sends the selected 
enclosure to iTunes, and the last one a-freshes all our feeds. 
Since some of these openilions am take a long rime, we als«> 
have a Progass Indiatior 

m no ^ 
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RubyRSS's Main Window 

Even simpler, the Add Feed panel has two iext Fields: one 
for the Feed’s name and one for the Ultl. F:ich Text Field has a 
t'orresponding litbel. Finally, we Itave an Add Button and a 
Cancel Button. 

# 0-f> .. , FlCjglir 


Feed Name: 
URL: 


RubyRSS's Arrays and Controllers 

The Main window' consists of tliree Table Views. Hie firs^t 
contains the names and post counts from the Feeds array. Ilie 
second displays titles from the Posts array. The final table 


( Cancel ) ( Add ) 


Add Feed Window 
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TIk^ coniimions IkHwcvd cjur IJI clL'incnts and tlic 
contiT>lIefs' outlets anti actions shoLikl seem straightfonvaixl 
enough. 1 won't into the details hene, bill f enanirage ytai to 
open up the nib in Interface Builder and gel a feel for the wiring. 

One Iasi cjuick step. Since our user interface uses a Web 
View, we need to add the WebKit, framework to our project. 
Riglu click on ilie Frameworks Ibkler in the Groups & Files tree. 
Select Add fi Existing Frameworks,,., In the Pile dialog, find and 
.Staled the WebKit-framework and select Add. in the next 
panel, jus! .street Add ag^iin. 

You on now compile and launch the a[^plication. Of course, 
it w^on't do much yet. We on add new^ feeds, hut we cannot 
ticiually r(;ad or parse them. All the basic IdihyCcK'ui ctKie works, 
but we still need to add sut)yKjrt ihr FecdTtx>ls and RuhyOSA. 

Parsing the Feeds 

Tile FeedTooLs lihraiy [irovides code for parsing, generating 
and auto discoveiy of RSS, atom and cdf feeds. We're cmly using 
a fniaiun of its abilities. If you want to know more, clieck out the 
web [)agc for FeecPTools and its sister project Feedl.^pckiter 
(http.//sptxkiii< >jigerx’oni/prc>jcas/feec!tcx))s/). 

Ijetls make a new' class to handle the interactions between 
FcedTcxils and our data m(xicl. Creaie a new' Ruby class named 
FeedReader-rb. 

require *tul:jy&einR' 
require * fEed_tools' 
require 'oHx/mcoa' 

OSX.require_t ranewurk * CoreData' 


FeedReader rlaaa uaes feed_tDolH to download and parae all 
the feeds. 

S then addB new and ent'lenures to the Managed Object 

Context. 

class FeedReader 

it fnaert nieiliods! heie 
end 

FeedReader starts by loading the required libraries. 
Obviously need Feed'fools and RubyCcxroa. 'rlie RubyGeiiis 
library lets us access any gem-installed libraries; therefore, we 
need tf> loaci lUibytK^ms before loading FeedTtxils, Most 
interestingly, the OSX.reqtnreJramewcjrk methexi lets u.s load 
Coetja frameworks. In this case, FeedRc^ader needs Cf>re Data. 

initUiIizeO 

4 Default CoTiiRtructc^r 

def initialise{inaln_controiler. not} 

«^ni<ilu_coni rol lor ^ niiiln_cniLLrol]Gr 
@Eiioc ^ moc 
end 

Initialize {) allows us to constnicl new FeedReader 
objects. It takes tw^t^ arguments: a reference to the main window^ 
controller, anti a reference to our managed (object context. 

refresbf) 

ii Gets the current list of feeds. Downloads all Feeds and 
adds Mew Fusts 

# and Enclosures to the Managed Object Context, 
def refresh 

feed entries = ^laincontroller,feeds 































tries.each (|data_feed| up43te(data_feed)I 
end 

FetxlRcadcT only exposes a single metlKKl to the ourskle. 
Refresh () ttenites over all the feeds, p^ifising eiich one to the 
update() helper function. 

updateO 

private 

UeJ-pec Function: updates a single Feed, 
def update(dflta„feed) 

feed ^ FeedTuols:tFeed.open(data_fend.urlj 
posts =“ feed.entries 

posts, each 11 post I add__post (post, dal:a_feed)) 
end 

Update {) extracts tht* list (if available ptxsis lor each feed, 
ft iLerates over I lie list of posts, caliing addjpost () for each one. 

itdd^QstO 

^ Helper Function: adds new posts to the given fi^cd. 
def Hdd_prJST (pofjt, data feed) 
title ’ post,title 
text - post.summary 

# check to see If this already ejcists.,, 
return if post_ex.istsf(title* text) 

# now make a new entity 

data_posr " DSX: :MSEritltyI>escription\ 

, inaeri KewOb j ec tForEnt 1 1 yFQrHaire_itiManagedObj ectContext (Post" 
@nioe); 

ilata_posi♦ setValtie_rart(ey(title, "title**) 
data_ post. setValue^forKey (text. “text ) 
data_post,setValae_forKoy(data_foed, "feed"> 

enclosures “ post,enclosures 

enclosures.each do |enclosure! 

add enclosure(enclosure, data„post)I 
end 
end 

Add_post{) extmm tlie ptxsFf> title and text. It then calls 
post_exists?{), checking if any pexsts in tlie mnnagetl 
object context alre^Kly have a matching title and text. Tf the fx>si 
doesn’t already exist, add_post () adds a new Post Entity. Ii 
tlien fills in the entity’s attributes and sets the feed relationship. 
Since we're using bi-directional relatic)nship.s, Core Data 
autotnaiirally adds tliis post to its Feed. Finally, add postf) 
iterates over the pn.st’s li.st of enclosures, calling 
add_enclosure{} for each one. 

fmst exijsts?(} 

§ Kolper FtKiction: determine If s post exists with the given 
title and 
# text. 

def poEt_existE?(title* text) 

request * OSX:ifJSFetchRequest.alloc,init 

description " OSX: :NSEiitityDescription\ 

. entiLyForNQme_lnManagedObJociContext (* Post'. ftnoc) 

request.se tEn I iLy[desc rlption) 


predicate = OSX; :NSFredlcate.prcdlcaieWlrhForjiiat ( 

"title like %# AND text like %§"* title, text) 

request.setFredicate(predicate) 

error * nil 

count = @inoc.countForFetchRequest_error(request, error) 

# if we have an error* assume the post doesn*t exist, 
if !error.nil? 

puts ***** Error ***** 
puts error 
return false 
end 

count > 0 
end 

Post_exists? () builds an NSFetchRequest tor all 
Post enlilies wh(xse Itlle and texi inach ihc given aigumenLs. We 
tiien use count For FetcliRequest_error_() to count the 
nunil'>er of matcliing Posts, For any numi vr greater Than j^ero, we 
return inie. Oiherwi.st*, we reiurn false. NcXe: we log any errors, 
but simply assume no matches are found, 

udd.mchsutvQ 

# Helper Function: adds a single Kncloaure Lo the given Post, 
def add_enclosure(enclDSure* data post) 

(irl enclosure.url 

isAudio = enclosure.audio? 

new^enclosure = OSX::NSEntityDeficrlption*\ 

i tifiertNewObj ectFor£ntityForName„inManagedObj ec tContext( 
“Enclosure’*, @troc): 

riew_enclouure,seLValue„forKey (url» "uri ") 
new_enc1OEure * setValue_forKey(isAudio * "isAudio") 
new„enclosure.selValue_forKey{daiu_pout* **post**) 
end 

Firuiily, add_eBclosure() adds a new Enclosure entity 
to the tiumagcd oliject context. It then fills the attributes, and sets 
the pcfst relationship. Agaiti, we have a l>i<iirMional relationship, 
m Cr)re [>ata automatically adds iliis Enclosure lo tlie Post's 
cnckxstires relationship. 

Now we just need to make our MainControher aware of the 
FeedReader. Add the Ibllowing line lo MainContmller's 
awakeFromNib() meih(xl: 

end. reader “ FeedReader. new [self, 

@app_dulegate.managedObjectContext) 

Tliis cteates a new Peedlfeider olxjecl. We just need to caD 
@feed_reader,refresh() wlK*ne\x*r the ii.ser presses the 
Uefesh Feeds button. However, tliis operatkjn on lake a while, 
especially when you subscrilx' to a loi of feeds. We don't want 
our UJ to freeze up. Also, we would like to let the user know that 
something is actiuilly happening. So, lefs have FeedReader refresh 
ihe feeds in a second lliread, and turn on the progrexs Ixir. 

Unfortunately, Ruby 1,8 is not thread safe. We cannot cal! 
Ruby cxxle from a .second (or third, or tbuiih..,) Objetiivc-C 
thread. However, wn ran use Ruby s internal llireads. Ruby uses 
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d green tlireading model. Basically, as far as the hardware knows, 
Ruby iLins in a single tliread, but the Ruby interpreter can time 
slice lierween several green threads. 

Ruby tlircads have some advantages and some 
disadvantages over processor threads. A full discussion is beyond 
the scope of this article, hut — l:xiTt<an line — they work fine lor 
our puqKxses. Thti user interlace will not freeze up while we 
refresh the feeds. 

Simply replace refreshFeedsAction() with the 
following code. 

neitf r^fre^hFeedsAcHonO 

This action refreshes all the feeds► 
def refrestiFeedsAc rlori (sender) 

Thread.new do 
tjK'gin 

^progress.startAniaationCself) 
e ed_r ea d e r * r e f re s h 
^progress.stopAnlmation(self) 
resjcue Exception e 
puts 

OSX;:NSApp.stop(self) 
end 

end 

end 

ib action trefteshFeedsAction 

The begin- . -rescue- - -end hkxks handle any 
exceptions tlirown in our worker lltread. II an error otaiis, it 
executes the rescue block, which logs the error and quits the 
application. 

Tm a lima Ix^liever in Failing fast. We don’t wtmi our axle to 
lumlaer aheiicl in an unknown state, At letjsi during development, go 
ahead and Ibrcx^ the application to stop as .s(x:)n as an error rxxiirs. 

Thai’s il. Opc'n up ihe RSS reader and add a few feeds. Click 
the Reftesh Feeds button, and watch the posts loll in. Quit tlie 
ai^plication, and then launch it again. C-ore Data automatically .saves 
all our diiia. 



Adfitc: Cjrtt AfTof d Cdrmf tiKhislwiI* 

irtUpM vtd #od IfklcA 

Aponte QirnkTimc D(CM Oiubks Adohs '' 





The Complete RubyRSS 


Tliis almost looks like a real application. Aimo.st. It still needs 
a lot of work. For example, the Uibles remain completely 
un.soited. Ideally, u.sei's will warn to filter them as w'elf By default 
w^e should probably filter out any posts that the user has already 
reati, Searcliing would also be nice. 

From a software engineering standpoint weVe playing fast 
and loase witli our threads here. The user can [^eifonn any 
niimlx^r of bad aaions (like quitting the aiiplication) wiiile the 
worker thread is still limning. We should pn>bably address that. 
But, you have to admit, we squeezed a ion of funcdtrntility 
out t>f a few hundred lines of axle. Ruby + Core l.>ata + Bindings 
makes a liigh-txxane combination. 

Next time, w^e will kxrk at using RubyOSA to .send 
enclosures to iTimes. We will also take a look at Rui>yCoa>a’s 
debugging options, imd kx)k at a lew' other cool trick.s as w^ell. 


\\\\ 
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Introduction 


Otic of the great Iscncflts of wtjrkiiig with Cocoa is that ilie 
A.Pls give the developer numerous features ‘'for free" One of 
those features is undo support. Any Cocoa application, without 
any work from the cievelotx.a; will nuiornatically get undo 
support at some basic level In this article I walk thruLigh 
exactly how Undo support works in Cocon and how you as tlie 
developer can lake some control over undo to provide ihe 
functionality you are kxiking lor. 

Overview 

Undo is one uf lho.se featin\"s that is rarely thouglit alx^ut. 
Most developers do not check it off as a featiiie in their 
applk:ation and most users do nol immediately kxik for it when 
reviewing a new application. However, it is a feature that if iKit 
present w^hen you need it. it is sorely missed. Kortunalefy, Apple 
has recognized this and included undo support for the developer 
so that, in most cases, we do not need to think alxxit it. 

Unfonunately^ wlien your application strays from tlie 
beaten path then you need to roll up your sieeves and make 
sure that undo sup]7orl works exactly as you expect it to. As it 
is Sul id, the devil is in the details, and having inconsistent undo 
support is worse tlian having none at ail 

What is Undo 

Apple defines undo as: 

An undo operation is a method for reverting a change to 
an object, along with the arguments needed to revert the 
change (for example, its state before the change) 

Undo is ixTfonned on a slack. What this means to those 
nor familiar with the term is that each action, or event, that is 
"undoable” is added to the top of the stack and therefore can 
Ik‘ removed from the slack. When you rernove an item from 
the stack it is also removed from tlie top and thus reversing the 
order it was added. For example, if you were editing a 
paragraph of text in a Cocoa NSTextArea and you typed "Hello 
World", that text wcjuld i:)e added to die stack as an undt>able 


event. If you then .selected “I lello’' and hit the text would 
liecome Ixikl and the atiton of bolding that selection of text 
would bv added to the stack. 



The reason thai the ‘‘.stack" aspect of this is impcirtam is 
when you want to undo something. When you choose undo 
then the ITrst time is removed from the top of the stack (in this 
example, the Ixjlding of ‘‘Hello’*) and undone. If the items were 
processed in a FIFO (First In, First Out) order then die text 
would Ix" deleted instead, wliidi is definitely not what the user 
would expect to iiappen. 

The Undo Stack 

What exactly is the stack? Probably the easiest way to 
de,scribe the stack is to describe how to pul things onto it. As 
an examiilc, lets say that we have a value that we want to be 
Lindoahle and therefore we want to add any changes to that 
value to the stack. To do that we w'cnild perform the following: 

(void) setNamo: (NSSt ri ngUopwt^ame;; 

r 

[[self -undoManager] registerUndoWUhTarget:j5e1f 
salector'^selector(setName:) 
object; [self namo]]; 

[iTLewMaiDe retainj ; 

[name release?) ; 
name = newName: 
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¥ot Those familtar with C<K,'tKa/Objeclivc-C, this is a lairly 
standard setter call to set llie attribute name. I'he change from 
the normal is the additional call to the NSLlndoManager. Note 
that in this example 1 am pas-sing it a reference to tlie object to 
call the methcKl on (.self), the method name to call (setNameO 
and the pretious value of tfuU attriliute* 

Inrernally, the NSUntloManager, is going to remenil>er these 
values that you arc passing in atid retain them as an undo e\'ent. 
Tliai event will tlien l>e stored on a stack (presumably in an 
NiSArray) to be recalled at a later time. Theix.'fore the stiick is 
really an array of struciures/objects that reference a taiget, a 
selector and another objea. One thing that is interesting in this 
design is that the object (the previous value of name) is actually 
reiaim^d by rlie undo event. Tliis guarantees tliai tlie value will 
still be around if die undo event is ever invoked. 

When the user of the applicatkin invokes die undo 
command, the last item added it) die NSlJndoManager Ls 
retrieved and then the selector is called ujion the target witli the 
object that is lieing passed in, thereby reversing the event. Of 
note: When an event is removed from the undo stack, it is 
automatically added to ihe redo stack. This allows a user to 
undt> and redo their actions as needed. 

Grouping Undo 

In add id on to lx:ing able to undo and redo individual events 
such as the setter above, it Is possible to group individual events 
together so diat they are undone and redone as a single 
openuion. An example of ihis would lie an extension of tlie 
example alxive. For instance, lets imagine that the setName: 
melltod above actually breaks the string apan into a finsi name 
and last name. And insiead of having an undo registration at die 
setName, we want to liave the fust anci last name register events, 
then grouping would come into play when the full name Is sen 

(void)setName:(NSString*)name: 

{ 

([self undoHanagerl beglnUndoCrouplngJ: 

NSArray 'words * [name componentaSeparatedByStriiig#'' "i: 
fself setFlrstNatte:[vordfi objectAtludex:0]: 

(self setLastNamf: [worHf* ob jectAtTndex: ll; 

[ [self undoMariagerl endUndoOrouplng] ; 

I 

{void}setFlrsLNaifie: (NSSl rlng’)name 
I 

I [self uiiduMiiriagor] rogislerllnrioWl tliTarget:self 
selector;#selector(setFlrstKame;) 
object:[self rirsiWame]!: 

[name retainl: 

[firstName release]: 
firstNajDe ” name; 


(void) setLastName: (NSSiring*) name 
I 

[[self undoKanagerJ registerllndoWithTa rgot :self 
selector;§ eg 1ecto r(setLastName:) 
object:[self iastNameJ]r 
[name retain]; 

IlastName releasej: 
lastName “ name; 

I 

As cm lie seen in the listing, the individual parts of die 
name have stored their changes in the NSUndoManager’s stack 
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hut the .setName: mL'llicKi dc)c?^ not .store its clianges in the undo 
sLick. Instead, ii starts a group, sets the individual components 
and then ends the grouping. What this <kK‘s is si ill the 
NSLIndoManager that all lindo evenus it receives l>etween the 
lx:gin and end are to Ix" [XTfonned together. By using grouping 
in an example like this you do not risk polltiiing the stack with 
a setName:, seiMrstName: and setkisiNanie: c*ill and thereby 
causing an issue when tlie user attenipls to undo the action. 

Naming the event 

In addition to Ijcing able to control the undo/retlo events^ 
it is also possible to name these events. Ihar name is them tised 
by the undo and redo menu items to lielp explain to the user 
exactly wliai they will be undoing and redoing, 

(void)setFirstName:(KSString*)name 

f 

|[jael F undoManagerl reglsterUndotflthTarget :selt 
seiector:0selector tseLFlralNatiie: J 
object: [self firstNainel j; 

undoManager] setActionKatne; 

NSI-ocal f^ndSr r ing(8''Firi5t Marne"* 

®"First Mame undo action')]: 

[name reia I rt]: 

IfirstKame release]: 
firstHonie " name: 

1 

The only cliange from the previtnis example is the addition 
tif lundoManager .setAcuooName:], This cull instructs the 
NSllntkjManager to attach tlie j>assed in ,slring as the name of 
the previous event, In this example, it attaches the name of 


“First Name” tes the event of selFirslName:. If the user were to 
IcKtk in the edit menu after changing the hrsf name they would 
,see something like ‘'Undo First Name”. A.s you can see, we 
localized the action name so that we can easily go back and 
Ux'aiize the name of the atlkm at a later time, 

!t should be noted that groupings can also be named. If 
an event and a grouping are both named then the grouping 
name will win nut. For example, if our setName; method also 
set the ActionName to “Name" then when the setName: method 
is called the edit memi would display “Undo Name” and not 
“Undo First Name” or “Undo Last Name”. 

Levels of Undo 

As am lx expected, since the NSUndtiManager actually 
reuiins tlie objects being j>assed around it is quite possible to 
Ixigin to have a memory issue. 'I'lii.s is esjxdaliy true if tlie 
object of the function call is in itself quite large. One option to 
help contain tliis Ls to limit the numixr or “levels" of undo 
available to the appliciiion. ill is is controlled by a simple call 
to: 

tlseir undoMaoa^er] setlpevel^OfUndo: lOl: 

wilich will limit the applicatitm to reincmlxring only the 
las1 lO undt) cvenLs. 

Blocking Undo Support 

As you can pRjl>al>ly imagine, since undo support is 
managed as such a low level (all the way down in the setters), 
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ir is possible to biiilc! up a large undo stack just by populating 
an oi)jec’i from anoiher scnirce. Fonunaicly, tiicre is a way lo 
avoid this. For example, imagine you are populating our 
exam[>le abject from an XML feed. Naairaliy, you do not want 
to Starr building up the undo stack while setting the values from 
tlie xml document but you do want to add to the stack when a 
user changes something, How can you instruct your 
application to tell the diffemnce? 

The secret is Lt> pause the undo regi^siration while loading 
your document and then resuming it after your load is 
complete. See the tdllowing example: 

(KyOb jec L' J bulMMyObjGClFroidXHTH: (NSXMT.Doeumerit *) doc 
i 

NSString Hempl'"lriJtNan)e = .,,: 

NSStritig *teinpLafitNaiiie “ 

NSUndoHanager ’undo = [self undoWanager] \ 

[undo disableUndoRes^ifitrationl: 

HyObject 'object = [(MyObject alloc] inil]: 

[object setFlrstNatneitempFlrfitNamel : 

[object setLastName:tempLastName]: 

[undo enabletJndnRegistratlonl ; 
returfi [object autoreleasej; 

1 

In this exanipic, we instruct the NSlJndoManitger to stop 
registering events and then we biiikl the data object and set its 
attributes. The data object itself has no kjiowledge of whether 
or not I he NSUndoManager is distibled (although we could 
check if needed for some reason) and continues to register 
events. The N^S Undo Manager receives these events and since it 
is disabled simply throws them away, When ihe oitject lias 



l:xten completely loaded we then turn the regisiraiiori back on 
so tiuii any events afterwards will be registered properly. 

Initializing the JNSUndoManager 

In all of lliese examples, I have just Ixx^n calling [self 
undoManager] to get a referenc'e to the NSlJndoManager In an 
actual program yon should have very few NSUndoManagers. Eiich 
NSlJndoManager should lx: iti a logical location. For instance, if 
you have a document st>1e application them each dcK’ument should 
have its own NSUndoManager, Otherwise you probal^ly only want 
(xic NSUndoManager for the entire application. 

To initialize an NSUndoManager, you simply call: 

NSUndoManager 'undoManager = [ iNSUndoManger alloc] inlt]: 

Naturally, you are going to want to hold onto a reference 
to this object so that you can make it available to other parts of 
your application. 

Getting the UI to use your 
NSUndoManager 

If you are going to build and/or use your own 
NSUndoManager then you will warn to lei the user interface 
access that same NSUndoManager to avoid having multiple 
slacks trying lo act on the same dam, Fc^nunalelyf all views get 
theii- NSUndoManager from their window and the wanclcw gets 
its NSUndoMatiager from its delegate. Therefore if you have set 
up your coniroller (or another object) as the delegate for your 
window, add the ftjlkjwing method call; 

- (NSUndoManager *)windowWiilReturnUndoManager:(NSWindow 
•)wl ntlow 

I 

return ($elf undoManager]; 

I 

Tlie window will then call this method to get its 
NSUndoManager, If you do nut sup[>ly a delegate then the 
winciow will initialize its own NSUndoManager. 

Conclusion 

Once ihe curtain has been pulled l)aek you can .see tltat the 
NSUndo.Manager is in faa a simple array containing .structures 
with two objects and a selector, llial is all there is to Undo. 
However that simplicity belies the power t)f the design. The 
apjilication of tliat simple data structure allows for the sense of 
wonder and awe that Is an application with a properly 
implemented undo subsystem, 

r f L 
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The Road to Code 

by Dave Dribin 


Nice and Gooey 

Writing your first 
Cocoa GUI interface 

V_ J 

Graphical User Interfaces 

'lliis Is the tenth artkle in Ihe Road to (AMk\ and we have yei 
to write art applit^Uion with a ^^mplue user interface, or GLU. We\v 
slut k to writing a)iniiKitid line appliaitk)as, which truly seem 
strange, given that Mac OS X Ls coaskiered one of ilie ix-st GUI 
environments. Hut, jls with learning tnany aaiiplcx Ut]>lcs, you've 
gol Id learn the Ixisks fxrlba' moving on to the more advancaJ 
topics. Well, you'll Ix" luippy to know tliat we Fiailly reiiched the 
point where w^e am start w'riting GUI appliralion-s for Mac OS X in 
Objedivt^-C. Qingrauilatit)ns! 
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fAppfluiloii 

ApptcScElpI Af.f}llcdJd(rn 

AppitScripi DocuniciiE boitd Aj»pticuQ(S 
AppleSfrlpt Dfopli; 
tdrbiDri Applptatcjn 

CiU E>aiT C-A{lpl<CdRiWI 


1 
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CocEu Oixuraenr-bis^ Appik^jof> 
CouH-fytticxi Aaoticitfofi 

A 

T 


Tbit pic^ect ispLicallor written in Db^octhw C 


(~ C^ccQ I i 


Figure 1: New Cocoa application project 

Name the pioject Hetio World and click Finish. So fan diis Is 
the same as creating a new Foundation Tool ap[)liaition as we have 
Ix^n <loing pa^viously. However, tills pmject has a different layout 
than cx>tnniand line kxjls. If you open some of ifie dl.sdosum 
riiangles in die Groups & Files stxtion on ilie left, you sliould see 
a list of files similar to liiose shown in Figua* 2. 


Leopard Only 

A word of warning Ixlbie getting Ux) tieep: now tiint Mac OS 
10 5 (Leopard) is available. I will be writing all examples in Xoxle 
3 and Jnted'acx* Builder X ^he new integrated develo]>nieni 
envinmineni or IDIL ilutt comes with Leopard. 'Itiis wiJl not only 
alTcxl Interfac’e Builder sacxfnslKas and iastniclitms, bui rlie ci>de 
will also lx‘ targetcxl to lAx>fxiid, as well, 1 will lie making lilxral 
use of Objective-C 2.0 profxrties, fast eniimemlbn, and g;irtTage 
ctjllectton. Tlie,se new features am simplify cxxle and m^ike it imm 
rc^adable, so J think all new axle going forwaal sliould take 
advantage of them. Since we haven’t gone over these lopla^ 
outside of the U^pcml ikiour article, I'll be going over rhein in 
more detail as we a>me ac'ros,s them. If you don’t have Letjfxiid or 
w'ani to target prevknis veision of Mac OS X, die simple eximiples 
well lx going over fi>r the time Ix^ing am lx* Ixiilt with minor 
nKxlificufion.s on Xaxk* 2.4.1 and Interface Builder 2.5. Ill try to 
point out any potential araus that are not Ixickward compatible. 

Creating a New Project 

Willi iJic icchriicalities out ol' tlie way, let's gel startetl. Open 
up Xtxxle 3 anti select the Rte > New Project... menu. ChixiHc 
Cocoa Application :ls in Figiin; 1. 
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|| Llello World 

1 Release 

Active Target 

Active BmIIc 

Crouos & Files 

It 

^ Hello v/orld 



▼ Classes 
T, Ottier Sources 


_H_ Hellc Wo!'id_Prefi>c.pch 
^ main.n 
▼ ^ Resources 
hfn 

► [j^ lifoPlist.strirgs 
^ 3! l/ainMenu.nii> 

► j rrame works 

^ Products 

Rgure 2: Gkob Application default files 
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Youll notice ir creates more than ihc single file that 
we Iiave seen thus fitn ll creates a main ,m source file and 
a few other resources. We’ll talk about all these files in a 
second, hut it turns out that this program is ready to run. 
So let’s not waste anymore time and see what Xcode gives 
us by default. If you select Build and Go from the toolbar 
or Run > Run from the menu bar, this will start our new 
application* You will get a new empty window, as in 
Figure 3- 



That’s pretty l)asic, Inji it's a fully functional Cocoa GLU 
application. You even gel a menu bar, as shown in Figure 
4. In fact, you need to quit our application to return lo 
Xcode so choose Hello World > Quit New Application to do 
I his now. 


f| Hello World File Edit Format 


Figure 4: Hello World menu bar 


YtHi many luve noitcccl the '‘NewApplication'' text in 
tlie Hello World menu, as shown in Figure 5, Xcode doesn’t 
setup the menus with the name of our application 
autoniaiically. Bin don't fret, we can edit the menus to our 
lieart’s content, and we'll change this text in a bit; 


Hello World 


File Edit For 


About NewAppheation 



Services 

► 

Hide NewApplication 

9€H 

Hide Others 

XSSH 

Show All 


Quit NewApplication 

_V-... 


Tigure 5: Hello World quit menu 


Befom gt)ing furilier, lets take a quick kK>k at the source code 
lluit XctxJe generates for us. lliere's only one srHin'e file and ilial’s 
main 4 m. Selea that to see whafs inside. If you're exfxxiing to see 
a hum h code iliiit sets up the menus and crKites a window, 
you'll fx.^ sorely dLsiippointetl, Our main function Ls ttuite sm^ill. In 
fact it’s only a single line: 


Listing 1: imdn function for Cocoa 
applications 

^ nfmrt <Coco4/Cocoa,h> 

irn tRiilntlfii argc, char ^jirgvfl) 

I 

( <* turn NSAppl 1 ca 11 onMaiTi (argc, {c ui.iii o hii r * *) ar gv) r 

I 

That's all the axle nmning this appliaition. Hie only oilier 
source file is the Hello World_Prefix.pch file, and tliLs file is 
only u.sed to lielp .spccxl op comfiile thtws. It’s called a pn^x 
Ixxtikr and can gatentlly lx- ignored. .So wliere do the window^ 
anti nx'nu.s come from? 

Interface Builder 

if you look in the Resources group, yoiiH ntxice a file named 
MainMenu • nib. A nib ille contains all tlte GUI ajniponents of a 
Gx’oa apfjlicadc^n In a st>rt of hee/x*xirietl state* Tltese nib files 
canmK lx edited in Xaxle* howtntf. 'Ilxa* is a new upplicatifm 
aiiletl Interlace Buikier for this. Ilouble click on MainMenu •nib 
and Xtxxie will auionuiiically o[Xai tills file kw you in Intertaa" 
Builder. As a hLstoiic note, the nib file extension stands for NeXT 
Iniertacx.^ Builder and ontv* agiiin shows ihe NeXl' lineage of Mac 
OS X. 

Once tills file Is tJixiied up in Inteifuce Builder, you will be 
pa^.sented witli a myitid tif new^ wincbws. Fve slu jwn a l>iRl’s^ye 
view of all the windows in Figuie 6. 
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Figure 6: Interface Builder windows 


'I'he two panel windows on the ri^^ht are nor part oi' our 
nib. The firsi one with the Window I den lily title is the 
Inspector panel This us how' we change various aUribiites 
of our GUI components. The Library panel contains all the 
“parts" that we curt add to our nil). The Main Menu, nib 
w indow' conUins all the “parts" that currently are part of our 
nib. Among these cornponents you ll see MainMenu and 
Window, The.se correspond to ihe freeze-dried main menu 
and window' of the Helhj World appUcation. The other two 
windows eorrespond to editable copies of the main menu 
and window of our application, wdiich is how^ we change 
them. 

Let's start by adding a text label to our w'indow^ You'll 
need to find the Libel component in ihe Library, The 
easie.si w'ay to dt) ihis is to type “lafrer into the search field. 
Once you find it, drag it from the Library panel onto your 
Window; as shown in Figure 7. 
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Figure 7: Adding a label to our window 


Now thai you have ihe iaht'i plat ed in your window, you am 
change the text. DouIdIc click on it and change die text to ' I lello 
World" You can also move the lalxH anyvvhere you like, just by 
dntgging. If you switch Ixick to Xcode and run the application, the 
window should liave our new label in it, as shown in I'igure 8, 


I 


Figure 8: Running Hellu World with the new label 

Stv how easy lliai was? We wea.‘ able to add a lalx^I to t)ur 
a]iplication without ev'en wiiting a single line of code. Interface 
Ruilder is a piwerhil GUI editor. As you start waiting more 
complex GUI applkatioas, you will be .sjx^nding a lot of time in 
Interface Builder, tis well as Xcode. 

Changing the Menus 

Before we start adding .some aistorn code to our ap|>liaitioti, 
let's fix up die application name in tlie menus. Go back to Interface 
Builder and ( lick in ilie window thai l(K)ks like a menu Iran You 
sliould lie able to ojKai the meiiLus imd see all the nieriu items, just 
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like 11 nonnai menu Ixir. However, you can now double click on 
tlie menus or menu items to change the text. I’or example, to 
change the text “Atx.>ut Newj\pplication'* to ""Alrait Hello World" 
open up llie New Application menu and double click on ilie About 
NewApplication menu item. You should now l^e editing tlie text, 
as shown in Figure 9. Change the text appropriately and hit 
Return. 


a 0 a 


MainMenu 


NiwAjpfltjcition 


File Edit Format 
Vbout Hello World! 


1.. 

Preferences... 


j Services 

> 

Hide NewApplication 

SH 

1 Hide Others 

X8§H 

Show All 


Quit NewApplication 

%Q. 


Figure 9: Editing a menu 


Now do tlif saiiK’ wiiii tiu' Hide ;ukI Quit nicriLi items, a.s wt^ll 
as the NewApplication menu in the menu Ixir. ’Ilie tiruil result 
should look like Figure 10 , 


mmwmm 


File Edit 

About Hello World 


MainMenu 

Format 




Preferences... 


Services 

> 

j Hide Hello World 


Hide Others 


Show AM 


Quit Hello World 

%Q 


Figure 10: Edited menu 


Actions 

Wl^ile you can do a lot using Interface Builder alt>nc, you do 
end up liLiving to write txxic that interacts willi Lite user interface. 
Interface Builder provides ways to hook up parts of the user 
intertaa^ witli code, as well Let's add a button to our window, but 
firsi delete llie lalK‘1 we added. Click on the lalx;l and delete it by 
preSsSing tlie Delete key. Now, we need to find a button in the 
Liliniry. It you type “button" into the lilirary's search held, you will 
see a bunch of dilTerc^nt button stylets to choose from. The standard 
Cocoa button is allied a Push Button and is die first one in the list, 
as shown in Figure 11. Drag die push button to your main window 
and change its text lo ‘Tress Me ” as shown in Figure 12. 

# ^ , . UbrlSrV 

>■ liJI Library 


I 


i 


\ 



/ ‘ f?"U5h 


Ttt* PiiSfiuUfir 4 A iuiM JiS ul VSCaitlifil 

Chat intfcepH a*i(i ^rt 

aciion goicc: n'5 


If you now go back to Xcode and run the application, you 
should see our edited menus. 


Figure 11: Buttons in the libraiy 
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r Press Me ^ 


Figure 12: Press Me button 



You an rtm the appliation as is, and yoy can even pa-ss ilic 
buUon, hul noli ling will liiipjx^n. We need to hook up the button 
to some code so we cun do sonietliing when the user piesses it. 

Let's create a new' class in Xcode anil name it 
HelloWorldController. Xcode will enrate tlie eni]>ly header 
and tlie iniplcinentalion files, as usual. We're going to create a 
metlKxl that gets called w'hen die Ixirton is pressed. Make the 
header and source file Tnatcb Listing 2 and listing % respectively, 
and save l x all files. 

Listing 2: HelloWorldControUer-h 

’ ■ V > Cocoa . h> 


^tniurface IlolloWorldController : N^object 
\ 

I 

{IBAcUon} preeaKet (Id) sender; 

©end 

listing 3: HeIloWorIdControIler.nl 

ffljipor I “Kel I oWu r 1 rlCont ro 11 er,h" 


eoen t at 1 on Hel 1 oWor 1 dCont ro 1 let 

- (TBAcrlonl pressMe: (id) sender; 

I 

I 

i^Gnd 


This class contains one niethocl pressHe:, tliai prims a 
message to the console when ailed. This method Inis a very 
specLil signature. It relum.s a lytx callal IBAction, and it takes 
one aigumeni of type id. 1'he IBAction return type is really the 
siime as void, meaning there Is no return value, with the exct?prion 
ihat ii marks thi.s mclluxl as an atHfm for Interface Builder. 

We haven't yet awered tlie id type, but it's not really important for 
this distatssion. We'll tackle id in a future article. Wli:ii's important 
is that adion methtxLs take a single id argument. 

Marking a mciliod an action method means you can acces.s 
this metliod from Interlace Builder. Before w^e an use it, we neetl 
to crcaie an iastante of Hel loWorldController lliat Inicrfacc 
Builder can scv. Co Ixick to Interface BuiltkT and seairli fur 
"nsoliject" to find the Object component in the librafy. Drag this 
over to the MainMenu.nib wintkrw, iis shown in Figum 15- 


m- 


Figure IS: Adding an NSObject to your nib 


Now go to tlie In^Dector panel, and click on the Identity tal>; 
it's the sixth tab from the left with the little "i” in a circle icon. 
Change the clans to HelloWoridController m\d liir Return. Hie 
|xinel should now look like Figuie 14. If Interfiice Builder does not 
allow you to choose HelloWoiidController, lx sure you’ve .saved 
ycHir files in Xccxle. 


# l?0 ^ ejwfitFgatr 


i ' O I # i ^ 






>€toaAaiww 

Action ,TV|Jfr M 

id 


Chkfet ~ I 


y Intirtacft BuUtigr 
HMim —— 

Object 10 191 

Loch ^ NcrfH im| Cinhyitrd) ^ 

Figure 14: Setting the dass of an NSObject 


Yoiill notice that t>nce tlie class is set to 
HelloWoridController, the pressMe: method also shows up 
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in the Class Actions .seetkjn. ff you don't Hce ttiis action tlien 
doulilc check ytxir cxxJe to niake .sure you six^Ued everytliing 
correctly. By adding oiir objea to tJie nib, weVe tTe<iied a freeze- 
dried instance* of our cla.sK. TfiLs meanw that one instance of our 
class will automatically lx ctvated when tlie application starts. 

With oiir (>bject in place and otir acrion visible to 
Interface Builder, we can hook up tlie action to our button. 
You do this by control draggingthe button to the Hello 
World Controller. By “control dragging” 1 mean you must 
press and hold the Conirol key whila clicking and dragging. 
Tliis action may be a bit strange, but you will use it a lot in 
interhice Builder. You should see a blue line follow your 
mouse as you drag. After you release the mouse button on 
lop of our object, you’ll get a popup window of possible 
actions you can connect the button to, as shown in Figure 
15, Click on pressMe: and Interface Builder will flash a 
hii to confirm that il hooked up ihe action. 
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Figure 15; Hooking up a button to an action 

Thar's ir! You have now hooked up rhe burton to our 
acrion [iieihod. Let's go back to Xcode and run our 
application to see if it worked. After our application 
launches, click the bimon a few times and check the 


console for any output. Xcode 3 no longer shows the 
Console window by default, hut you can open it with the 
Run > Console c'ommand, or Command-Shift-R. If ihc 
action was pro|)crly hooked up in Interface Builder, you 
should see output in the console similar to this: 

200a-D2-06 10:43a5.4?9 Hello World [5664: lObl Rulton pressed 
2008-02^6 10^43'16.079 Hello World [5664: lOh] ButtOD pressed 
2008-02-06 ]0:43:19.479 Hello World[5B64:10b] Buctoo pressed 
If you want to always see the Console window like 
previous versions tjf Xctjde (I do), you can diange dii.s in the 
Xcode [^references. Under the Debugging tab, in the On Start 
pc^pup, chfjose Show Console. 








^ 1 # 

V 


IT Received Aclions 


( pffessMfr: _ i^sh 


Figure 16: Received actions 


Since actions are a two-way relationship, you can also 
verify this by viewing the connections of the button. 

Push buttons arc not the only Clll components that 
send actions. Menu items, checkboxes, radio buttons, and 
popup buttons all send actions, 'the procedure for hooking 
these up Is always the same. Create an action method in 
your code and llieti control drag in Interface Builder to 
hook up a component to an action, Now that you know 
how^ to do it, I woiVr go over the detailed procedure in the 
future. 

Outlets 

Actions are great, but that’s only half the puzzle. We 
still need to be able to get information out of the GUI. If 
we I lave a text field, for example, we will probably want to 
use what the u.ser entered into it. Let's cover that now. 

hind the Text Field component in the Library by 
.searching for “texi field” and add ii to I lie window by 
dragging it from ilie Library, just like we did with the label 
and button. Be sure not to mistakenly choose the Text Field 
Cell, which is not the same tiling. Place the text field above 
llie button, as shown in Figure 17. 
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Figure 17: Added text field 

If we now run ihe application, you will be able to type 
into the text field, a.s you might expect. Getting what you 
type out of the text fieid requires .some code. Back in 
Xcode, add an tastance variable named _textField to our 
class, as shown in Lisling 4, and save the file. 

Listing 4: HelloWorldController-h with an 
outlet 

iliiport <Conoa/Cocoa. h> 


#itit©r£fice HelloWorldCont rol ler : HSOb flirt 
I 

rBOiifii?! * .textField: 

1 

(iliActlotd prsj3f:Me: (id) sender: 


This instance variafde is declared like any other 
instance variable, except it has the IBOutlet prefix f>efore 
ihe type. Again, this is for integral ton witli Interface Bulkier 
and marks this instant:e variable as an aiitlet. Outlets am 
he luKjked up to GUI components in Interface Builder, and 
that’s ihe next step. 

Back in Interface Huilden cxaitrol drag from the Hello 
World Controller lu the text field. Again, when you release 
the button, you should get a popup window allowing you 
to select textField. as shown in Figure 18, Choose 
_textField to make tlie connection. You can verify the 
connection by looking at the Connection ial> of the 
inspector panel, if yoti like. 
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Figure 18: Hooking up an outlet 

Wilii llic ouUrt cotmecikm made, we can now use tair 
_textField instance variable. It will automatkally tx’ set at 
application load time. You'll notice tlie type of _textField is 
NSTextField. Tliis Is tile Qxxra class for text field controls. It 
has many methods, but the one we are interested in is 
stringValue. Tliis method, uasurprisinKly, returas the contents 
of the text field as an NSString. Mexlify our action method to log 
this value when die button is pressed, as shown in Listing 5. 

Listing 5: HelloWorldControUer.m using an 
outlet 

^import ^HelloWorldController 

tlup I pirenta Uon HelIoWorldController 

* (TBAcritm) pre0eMe; (id) senderr 
f 

NSLog(i'*Button pressed*) r 

NSLoa(rText field in: W\ LtextField stringValue]): 

1 

Now am the applicaiion ag^fn. Type ,some text intt> ilie text 
field, such :j 5 “Hello!", and press ilie l)unon. You should see text in 
the coRsole window similar to: 

zoos-02-06 11:57:50.697 Hello World{6089:10b] Button pressed 
Z00B-0Z-D6 11:57:50.69B Hello World [6089:1Ob] Text field is: 
HelloI 

YouVe just hooked up and used your first outlet! Outleis 
can be used to hook up any GUI component to your code. 
They are used quite a bit, as you will see once you start mare 
Cocoa programming. With actions and outlets, we can create a 
real GUI application. 


Rectangle Area Calculation 

Let’s bring back our oid friend from a few articles ago, the 
Rectangle dai. Add a new class named Rectangle to your 
application, and make sure the lieader and source files match 
Listing 6 and Listing 7» lespeatvely. 

Usdng 6: Rectangle.h 

r t < Foiinda t ion / F o > i n d a r i r>n. h > 

@if; ter face Rectangle : l^SObject 
! 

float _leftX: 
float _bottcfiaY: 
float : 

float _haight: 


%COperry flont leftX: 

^property float bottomY; 
jfpropexiy float width: 

B^property float height: 
gpEOperly (readonly) flinii area: 

»lpKipetty (leadoiuy) float perimeter: 

(id) inltWithUftX: (float) leftX 
bottomY: (float) bottomY 
rightX: (float) rightX 
topY: (float) topY: 

#eod 

Listing 7: Rectangle.m 

ffimport "Rectaagle.h" 

@inipleti!entation Rectangle 

iisynthesUe leftX - J.eftX: 
tsynthesixe bottomY “ _b^tiofflY: 

^synthesize width - jwidth: 

^synthesize height “ ^height: 

- (Id) inltWithLeftX; (float) leftX 

bottomY: (float) bottomY 
rlghtX: (fhiat) rightX 
topY: (float) topY 

[ 

self = [super init]: 
if (self = nil) 
return nil: 

_lefi:X = leftX: 

_boitoa3Y = bottomY: 

_w1dth = rightX ■ leftX; 

_height = topY ■ bottomY; 

return self; 

I 

' {float) area 

I 

return „wldth * .height: 
i 

- (float) perimeter 
{ 

retum (Z*_width) + (2^_h^ight}; 

) 

ieiid 
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Tins Rectangle class is similar to wkir weVe useti in 
pi'evious articles, except tint Ive updated it witli Objective-C 2.0 
projTerties. In die lieadei^ file, you1l see several @ property lines. 
The,se declare lm>pcrties and must match the following syntax: 

0pi-opeirty (options) typo 

The type is any valid Objective-C type, such as C primitives 
or ObjcctivC’C diLSses. In our case, we're using the float 
primitive tyjx?. One of the options available is readonly. We 
used tliis on the area and perimeter prt>|xities. Another option 
LS readwrite. Hi is is the defaiiit, which is why we don't specily 
it on the a^t of our jmiixrriies. Tlie ^property dechration 
declares accessor methotls for us. A readonly propert}*^ declares 
a getter method only while a readwrite property declaies lx)th 
a getter and a setter. Thus, tliis single line: 

^prpperty flcat leftX: 

is die siiioe as declaring dicse two mt:thocis: 

- iflost) leftX: 

(void) aetLeftX: (riosl) leftX: 

lliere are other options, but we don’t need to know alxiui 
them jiLst yet. It ger.s even liettei-. Inside the source file, die 
@ synthesize key word generatti,s meihod implementations for us. 
Thu.s, this single line: 

leftX = _XeftX: 

is the same as these eiglit lines of axic: 

- (float) ieftX: 

I 

rtftui'n 


[void] setLaltX; [tloaL) leftl; 

I 

_U^lK - leftX; 

} 

As you can Ksee, properties can save us lots of monotonous 
typing. You do need to match up profxrrty names io instance 
variables, Ixit that’s a snrtll price to }Xiy. And as a Ixjnus, ii' you 
name your instances variables the Siime as your propeities, you 
don’t need die pan of die @synthesize lines. 1 still prefer 
undenicore prefixes for my instance vaiiafiles, but dial's just 
personal taste. 

You’d notice dial wc still implement the area and 
perimeter methods. Tliis is completely Icgtd, and it shows [low 
you can mix property deciarations and custom method 
implementations, if you need to do so. We need to do it liecause 
these mediocls are calculations and liave no cxm’sponding instance* 
v^triables. 

Since properties are Ijeopard-only, this axle will not compile 
in previous vei:siuns of Xaxic, If you w'iint to run this on earlier 
versions of Xcode and Mac OS X, you'll need to teplace all die 
@ property lines wilii their a>rresponding accessor methexis. 

We’re now going to create a GUI around this Rectangle 
class to alkw die user to pertbnii area and perimeter calailations. 
First, .st!L up our user interfiice in Inteihicx:* Buikler Dnig labels, text 
fields, and a button into die window, and resize die window so it 
looks like Figure 19- 
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Figure 19; Rectangle window layout 


MnterfacE HelloWorldController i ^^SObject 

IBOutlet NSTeactFleld ' _wldthFleld: 
iBOutlEt NSTextField * heightFieldr 
IBOutiet NST<?xtField * _i»rie3T^be] : 
TBOurlet HSTesrtFieXd * _perlnilterLabel: 

Rectangle * _rectangle; 

I 


- (IBAction) calculate: (id) sender; 


^1th the?>e oiiilt'Ls and adion.s in place, save tills file, go back 
to Interface Builder, and make tlie appropiiate connections. Jf you 
did it properly, the conneaioas for Hallo World Controller should 
look like Figure 21. 


Wlic!i yoifne dragging things around and setting up the GUI, 
you will probably see dashed blue lines pop up, as sho\\Ti in Figure 
20. These are guides that give you 1 tints alxmt Apfile's Human 
Interface Guideline's (HIG). Tlie HIG is a doaiinent that .specifies 
many guidelines about designing a^nsistent user inrerfaties for Mac 
OS X. It s a big dtK'ument, anti a gtx>d read if you pUn on doing 
any serituis Gx’osi devdopruenL Part of tite inlbnnation included 
in die HIG is spacing guidelines of aanponents, such as Ikw many 
pixels shouki Ix" used as Ixmier for windows. Uickily, Interface 
Builder shows tis iltese blue HIG guides .so that we dtm'l have to 
cx>uni pixels tt> ntake sure we’re laying things out comettly. 


#1 ^ Hello World Controller Connections 
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Figure 20: Rectangle window with HIG guides 

With our u.ser interlace in pktee, we need to go Ixick into 
Xcfxle In hfKik up rhest' componems. Modify die 
HelloWorldController-h header file to match lasting 9. 

Listing 9: HellnWorldControUenh for 
rectangles 

<Cocoa/Cocoa.h> 

#class Rectangle: 


Figure 21: Connections for Hello World Conti'oller 

Now, we am finish implementing our contmller class. Modify 
the HelloWorldController soua'e file to match Listing 10. 

Listing 10: HeUoWorldContraUenm for 
rectangles 

if impart “HelloWotldCouLroll^r.h" 
llmport **Rectangie.h" 

^impleusientation HalloWorldController 

- (id) init 

I 

self “ [^uper Initj: 
ii (seif ni1) 
return nil* 

rfeotaiiglG - ll^tecLani^it allocj initWitKLefLX: 0 

bottoraY: 0 
rifbtX: 5 
topY: tOl: 

return self; 

1 

- (void) updateAreaAndPerlmeter 

I 

[_,areaUbe] fletFl oat Value: _ rectangle, area 1; 

LparimterLabal setFloatVaiue: ^rectangle*perimeter]: 

1 
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>f3Vl/c> 


- {iBAction) calculate: (id) aendar 
\ 

width = LwidthField floatValue]: 
^raCtangle/b^ighL * [_heightFlelL floatValue): 
[seJf ui>dareArcaAiidFeri]iiEtarl: 


- [void) awflkeFrouiHib 
( 

LwidtiiFiaid setFloatValue: rssi.iahglc*width] : 
i bi*igblFiald secTloatValue: _!:^ctnngle*height|; 
lee .f apdateAreaAndPeriinf-Tar]: 




We've IkkI Co tills up a liit, hur it*s ^still pmtty siniplct In 
our a>nstnictorj we creaie a new Rectangle instance with a 
wkllli of 5 anti a height of 10. Otif calculate; action sets the 
rectangle's width and lieighi from the text fields, using llie 
f loatValue meilitxi. It tlien calls updateAreaAndPerimiter 
to set the area and periniefer labels acasrding lo llie rectangle's 
current area and penmeter This code also demonstrates anollicT 
lieneflt of properties: you can use the dot notatum to access them. 
Thus, iaslead of tnlllng setter meiliocis: 

' (IBAction) calculalG; (id) sEuder 
I 

f set¥idth: [^widthField floatValuell: 

Lrectans^ie setHelght: h,heightFi»:l;f floatValue] j: 

(self updaieAreaAmlPeriiEeterJ; 

I 


we can use Use d<a otJiation, _rectangle,width as 

shown in Listing 10. 

llie only other new bit is the awakeFromKib melhrxf 1liis 
is called auioTnaticrally by Cikxiq at application startup. We use this 
to set up the initial values of ihe text fields and laliels when our 
application is started. You’d think we could do this in our 
consiRicttir, hut iliere's a bit of a problem with that. 


A ^ rs 


VVindew 


Rectangle Width: f 5 


Rectangle Height: 110 
Rectangle Area: SO 
Rectangle Perimeter; 30 


Caiculate } 


Figuie 22: Initial Hello World window 


RemcmlKT that objects inside a nib file are "freexe-dried” 
or “put to sleep” when Interface Builder saves the nib file. 
When you application rims, tlicse saved objects are 
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when a non-domain name product 
is purchased. Limitations apply. 


'‘rccun.sliluied" or “awoken” at applicaiii>n launch lime. I’he 
problem is that we clon’l know w!ial order these objects are 
awoken and creaicd. Thus, the text fields and labels may not 
be initialued when our constructor is called To get around 
this situation, Cocoa first iastantiatcs all steeping objects in 
the nibj and then calls awakeFromNib on each of these 
objects. You don't haik^ lo implemem awakeFromNib, but 
we take this opportuniry^ to setup itie initial GUI state. As a 
rule, if you need to work with outlets, you must not do so in 
the constructor Use the awakeFomNib method, Tlius, 
wlien our appliculU)n is first run, you will see a window that 
looks like Figure 22 (above). 

We can now change the width and heigtii and click the 
Calculate button, if everything went as planned, the area and 
perimeter w^ill be updiuxi as shown in Figure 23. 

^ ft O O. ■. Window _ 

'•n\ lY I ■ ■ ■ III--—. .. 


I Rectangle Width: i 2 1 

■f 

\ Rectangle Height: 4 t 

I Rectangle Area: 6 | 

i Rectangle Perimeter: 12 [ 

I ,_, 1 

( Calculate y ( 

f /f} 

Figure 23: Calculated area and perimeter 

Conclusion 

Well, how alxDut that[ You've treait^d your first honest-to- 
gcx)dness Mac OS X Gl fl application. As you can sa;, it often does 
not take that muc:li ctkIc lo [mKiuce nke looking ttser interfaces. 
Interface Builder is tile key to this atst^ Nrrw tliat youVe got the 
Ixisics of Interhicv Ikiikk^r and GUI Mac OS X applic'ations down, 
we can move on uj bigger and Ixflter topics, llie full sotiice to ific 
projed will Ik* availal>le for downlojid from the MacTech wel:isite, 

'Jill 
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THE MACTECH SPOTLIGHT 


Founder, Pleasant Softivare 

http://www. pleasonfsofiware.com 




What do you do? 

I’m the founder and 
main developer of Pleasant 
Srjftware. 

Pleasant Software has 
been developing and selling 
high quality software products 
(or the Macintosh since 1989^ 
Currently* our three main 
products are “Dbercastcr” 
whicli is the most advanced 
podcast production suite for 
the Macintosh* “ShowMacster’ 
which revolutionises video 
conierencing l>y seamlessly 
extending Apples iChat 
application and TiP'', a free 
lool to present video from any 
webcam on the desktop. 


How long have you been 
doing what you do? 

First programming in 1982 on an Aj>ple 11 in school* 
developing Mac software since i9B8 starting with MPW on 
a Mac SE. 

What was your first computer: 

EACA VideoGenie I (a TRS-SO clone) 

Are you Mac-oniy, or a multi-pla^orm person? 

All current main projeas are Mac only Obi-C/Cc>ct)a 
applications, ‘riiere's also some softw'arc IVe written in pure 
Java (with Swing GUI) a while ago, which I still support 
(running on Mac it Windows). 1 also used to work as 
freelance developer and consultant, wUkh was all Windows 
stuff. 

What attmets you to rewfong on tbeMac^ 

rhe Cocoa framework and Objeclivc^C. 1 also 
personally have used Macs for more than 19 years and I 
love Mac OS X... 


n 




What*s the coolest 
thing about the Mac? 

From a developer's 
perspective: Cocoa! fVe 
worked v\iih a lot of 
framew^orks during the 
last 2 decades and 
Cocoa Is clearly one f>f 
my ah.sf>lute htvorites. It's 
easy to learn and 
extremely powerful! It 
saves a lot of work* 
especially for small 
companies like mine. 
Tm pretty^ sure that 1 
couldn’t have realized a 
project like OlTercaster 
without Qx'oa, 


If I could change 
one thing about 
Afpl^OSX, Id: 

rd get rid of closed systems polity like Mac-only 
functions in iSync or the missing/closed SDKs for AppleTV 
and iPod (classic/nano). The announcement of an iPhone / 
iPtxl Touch SDK is definitely a step in die riglu direction, 
Weil see how open this SDK will be... 

What*5 the coolest tech thingyou'm done using OSX? 

Back in 2001 1 Ixiuglit a PowerBook G4/400 I'itanium 
with Mac OS X lOJ and moved into the Alpujaras/Spain for 
3 months to write a quite complicated and sophi.sticated 
business solution program. So I did* in a ""Cortijo" on the top 
of a mountain, without access to the Internet or AC power 
(only one solar panel with an AC converter). That 
application was a tnie ^'greener Apple” project. .And it was a 
really great experience! 

We next way Fm going to impact IT/OS X/tbe Mm 
universe is: 

To quote Apple: We do not comment on future 
products :) But Leopard introduced a lot of great 
teclinologies and 1 iniend to use diem... 


ill 


yew or sometm you know belongs in the MncTedi SpotS^t kt t/s know! Send deltas to ediforiol^mactech.com 
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'Ulie Ute^-t AviA ^i-bk t)CtH‘A^ 

At Small Dog Electronics, we carry the newest Mac stuff, as well as the older 
goodies you're looking for Often when Apple announces a new product, 
we have access to older models, many with a significant price drop, 

Check our new website for both new toys and tried & true favorites. 


kAo(fAtA^tA\}{t 


We know Macs, and we know them well. If there's a question we can't 
answer, we'll find it for you. Every member of our staff (even the ones not 
in Sales) is a certified Apple Product Professional, and over three-quarters 
of us have also received our Apple Sales Professional status. 




We pride ourselves on being a business with multiple bottom lines, which 
includes an active commitment to social responsibility and environmental 
initiatives. We offer proper disposal of electronic waste for our customers, 
and this yean we’re hosting our 2nd Annual Free eWaste Recycling Event on 
April 19th at our S. Burlington location. But even if you don't live in the area, 
when you purchase from Small Dog, you're helping to support a greener environment! 

Read more about our ewaste recycling program and annual event at Smalldog.com. 
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